Additional documentation; fixed issues with Clang integrated assembler and different versions numbers for LLVM Clang and Apple Clang; fixed missing header in DSA class

1 files changed, 103 insertions, 14 deletions

diff --git a/osrng.h b/osrng.h
index c2acae8a..cb77de14 100644
--- a/osrng.h
+++ b/osrng.h
@@ -1,7 +1,11 @@
-#ifndef CRYPTOPP_OSRNG_H

-#define CRYPTOPP_OSRNG_H

+// osrng.h - written and placed in the public domain by Wei Dai

 

 //! \file

+//! \headerfile osrng.h

+//! \brief Classes for access to the operating system's random number generators

+

+#ifndef CRYPTOPP_OSRNG_H

+#define CRYPTOPP_OSRNG_H

 

 #include "config.h"

 

@@ -17,19 +21,26 @@
 

 NAMESPACE_BEGIN(CryptoPP)

 

-//! Exception class for Operating-System Random Number Generator.

+//! \class OS_RNG_Err

+//! \brief Exception thrown when an operating system error is encountered

 class CRYPTOPP_DLL OS_RNG_Err : public Exception

 {

 public:

+	//! \brief Constructs an OS_RNG_Err

+	//! \param operation the operation or API call when the error occurs

 	OS_RNG_Err(const std::string &operation);

 };

 

 #ifdef NONBLOCKING_RNG_AVAILABLE

 

 #ifdef CRYPTOPP_WIN32_AVAILABLE

+//! \class MicrosoftCryptoProvider

+//! \brief Wrapper for Microsoft crypto service provider

+//! \sa \def USE_MS_CRYPTOAPI, \def WORKAROUND_MS_BUG_Q258000

 class CRYPTOPP_DLL MicrosoftCryptoProvider

 {

 public:

+	//! \brief Construct a MicrosoftCryptoProvider

 	MicrosoftCryptoProvider();

 	~MicrosoftCryptoProvider();

 

@@ -42,7 +53,12 @@ public:
 	typedef unsigned long ProviderHandle;

 #endif

 

+	//! \brief Retrieves the CryptoAPI provider handle

+	//! \returns CryptoAPI provider handle

+	//! \details The handle is acquired by a call to CryptAcquireContext().

+	//!   CryptReleaseContext() is called upon destruction.

 	ProviderHandle GetProviderHandle() const {return m_hProvider;}

+

 private:

 	ProviderHandle m_hProvider;

 };

@@ -53,12 +69,20 @@ private:
 

 #endif //CRYPTOPP_WIN32_AVAILABLE

 

-//! encapsulate CryptoAPI's CryptGenRandom or /dev/urandom

+//! \class NonblockingRng

+//! \brief Wrapper class for /dev/random and /dev/srandom

+//! \details Encapsulates CryptoAPI's CryptGenRandom() on Windows, or /dev/urandom on Unix and compatibles.

 class CRYPTOPP_DLL NonblockingRng : public RandomNumberGenerator

 {

 public:

+	//! \brief Construct a NonblockingRng

 	NonblockingRng();

 	~NonblockingRng();

+	

+	//! \brief Generate random array of bytes

+	//! \param output the byte buffer

+	//! \param size the length of the buffer, in bytes

+	//! \details GenerateIntoBufferedTransformation() calls are routed to GenerateBlock().

 	void GenerateBlock(byte *output, size_t size);

 

 protected:

@@ -73,14 +97,22 @@ protected:
 

 #endif

 

-#ifdef BLOCKING_RNG_AVAILABLE

+#if defined(BLOCKING_RNG_AVAILABLE) || defined(CRYPTOPP_DOXYGEN_PROCESSING)

 

-//! encapsulate /dev/random, or /dev/srandom on OpenBSD

+//! \class BlockingRng

+//! \brief Wrapper class for /dev/random and /dev/srandom

+//! \details Encapsulates /dev/random on Linux, OS X and Unix; and /dev/srandom on the BSDs.

 class CRYPTOPP_DLL BlockingRng : public RandomNumberGenerator

 {

 public:

+	//! \brief Construct a BlockingRng

 	BlockingRng();

 	~BlockingRng();

+	

+	//! \brief Generate random array of bytes

+	//! \param output the byte buffer

+	//! \param size the length of the buffer, in bytes

+	//! \details GenerateIntoBufferedTransformation() calls are routed to GenerateBlock().

 	void GenerateBlock(byte *output, size_t size);

 

 protected:

@@ -89,34 +121,82 @@ protected:
 

 #endif

 

+//! OS_GenerateRandomBlock

+//! \brief Generate random array of bytes

+//! \param output the byte buffer

+//! \param size the length of the buffer, in bytes

+//! \details OS_GenerateRandomBlock() uses the underlying operating system's

+//!   random number generator. On Windows, CryptGenRandom() is called using NonblockingRng.

+//! \details On Unix and compatibles, /dev/urandom is called if blocking is false using

+//!   NonblockingRng. If blocking is true, then either /dev/randomd or /dev/srandom is used

+//!  by way of BlockingRng, if available.

 CRYPTOPP_DLL void CRYPTOPP_API OS_GenerateRandomBlock(bool blocking, byte *output, size_t size);

 

-//! Automatically Seeded Randomness Pool

-/*! This class seeds itself using an operating system provided RNG. */

+

+//! \class AutoSeededRandomPool

+//! \brief Automatically Seeded Randomness Pool

+//! \details This class seeds itself using an operating system provided RNG.

 class CRYPTOPP_DLL AutoSeededRandomPool : public RandomPool

 {

 public:

-	//! use blocking to choose seeding with BlockingRng or NonblockingRng. the parameter is ignored if only one of these is available

+	//! \brief Construct an AutoSeededRandomPool

+	//! \param blocking controls seeding with BlockingRng or NonblockingRng

+	//! \param seedSize the size of the seed, in bytes

+	//! \details Use blocking to choose seeding with BlockingRng or NonblockingRng.

+	//!   The parameter is ignored if only one of these is available.

 	explicit AutoSeededRandomPool(bool blocking = false, unsigned int seedSize = 32)

 		{Reseed(blocking, seedSize);}

+	

+	//! \brief Reseed an AutoSeededRandomPool

+	//! \param blocking controls seeding with BlockingRng or NonblockingRng

+	//! \param seedSize the size of the seed, in bytes

 	void Reseed(bool blocking = false, unsigned int seedSize = 32);

 };

 

-//! RNG from ANSI X9.17 Appendix C, seeded using an OS provided RNG

+//! \class AutoSeededX917RNG

+//! \tparam BLOCK_CIPHER a block cipher

+//! \brief Automatically Seeded X9.17 RNG

+//! \details AutoSeededX917RNG is from ANSI X9.17 Appendix C, seeded using an OS provided RNG.

+//!   If 3-key TripleDES (DES_EDE3) is used, then its a X9.17 conforming generator. If AES is

+//!   used, then its a X9.31 conforming generator.

+//! \details Though ANSI X9 prescribes 3-key TripleDES, the template parameter BLOCK_CIPHER can be any

+//!   BlockTransformation derived class.

+//! \sa X917RNG, DefaultAutoSeededRNG

 template <class BLOCK_CIPHER>

 class AutoSeededX917RNG : public RandomNumberGenerator, public NotCopyable

 {

 public:

-	//! use blocking to choose seeding with BlockingRng or NonblockingRng. the parameter is ignored if only one of these is available

+	//! \brief Construct an AutoSeededX917RNG

+	//! \param blocking controls seeding with BlockingRng or NonblockingRng

+	//! \param autoSeed controls auto seeding of the generator

+	//! \details Use blocking to choose seeding with BlockingRng or NonblockingRng.

+	//!   The parameter is ignored if only one of these is available.

+	//! \sa X917RNG

 	explicit AutoSeededX917RNG(bool blocking = false, bool autoSeed = true)

 		{if (autoSeed) Reseed(blocking);}

+

+	//! \brief Reseed an AutoSeededX917RNG

+	//! \param blocking controls seeding with BlockingRng or NonblockingRng

+	//! \param additionalEntropy additional entropy to add to the generator

+	//! \param length the size of the additional entropy, in bytes

+	//! \details Internally, the generator uses SHA256 to extract the entropy from

+	//!   from the seed and then stretch the material for the block cipher's key

+	//!   and initialization vector.

 	void Reseed(bool blocking = false, const byte *additionalEntropy = NULL, size_t length = 0);

-	// exposed for testing

+

+	//! \brief Deterministically reseed an AutoSeededX917RNG for testing

+	//! \param key the key to use for the deterministic reseeding

+	//! \param keylength the size of the key, in bytes

+	//! \param seed the seed to use for the deterministic reseeding

+	//! \param timeVector a time vector to use for deterministic reseeding

+	//! \details This is a testing interface for testing purposes, and should \a NOT

+	//!   be used in production.

 	void Reseed(const byte *key, size_t keylength, const byte *seed, const byte *timeVector);

 

 	bool CanIncorporateEntropy() const {return true;}

 	void IncorporateEntropy(const byte *input, size_t length) {Reseed(false, input, length);}

-	void GenerateIntoBufferedTransformation(BufferedTransformation &target, const std::string &channel, lword length) {m_rng->GenerateIntoBufferedTransformation(target, channel, length);}

+	void GenerateIntoBufferedTransformation(BufferedTransformation &target, const std::string &channel, lword length)

+		{m_rng->GenerateIntoBufferedTransformation(target, channel, length);}

 

 private:

 	member_ptr<RandomNumberGenerator> m_rng;

@@ -152,12 +232,21 @@ void AutoSeededX917RNG<BLOCK_CIPHER>::Reseed(bool blocking, const byte *input, s
 

 CRYPTOPP_DLL_TEMPLATE_CLASS AutoSeededX917RNG<AES>;

 

-//! this is AutoSeededX917RNG\<AES\> in FIPS mode, otherwise it's AutoSeededRandomPool

+#if defined(CRYPTOPP_DOXYGEN_PROCESSING)

+//! \class DefaultAutoSeededRNG

+//! \brief A typedef providing a default generator

+//! \details DefaultAutoSeededRNG is a typedef of either AutoSeededX917RNG<AES> or AutoSeededRandomPool.

+//!   If CRYPTOPP_ENABLE_COMPLIANCE_WITH_FIPS_140_2 is defined, then DefaultAutoSeededRNG is

+//!   AutoSeededX917RNG<AES>. Otherwise, DefaultAutoSeededRNG is AutoSeededRandomPool.

+class DefaultAutoSeededRNG {}

+#else

+// AutoSeededX917RNG<AES> in FIPS mode, otherwise it's AutoSeededRandomPool

 #if CRYPTOPP_ENABLE_COMPLIANCE_WITH_FIPS_140_2

 typedef AutoSeededX917RNG<AES> DefaultAutoSeededRNG;

 #else

 typedef AutoSeededRandomPool DefaultAutoSeededRNG;

 #endif

+#endif // CRYPTOPP_DOXYGEN_PROCESSING

 

 NAMESPACE_END