diff -r e1b950c65cb4 -r 837f303aceeb epoc32/include/random.h --- a/epoc32/include/random.h Wed Mar 31 12:27:01 2010 +0100 +++ b/epoc32/include/random.h Wed Mar 31 12:33:34 2010 +0100 @@ -19,9 +19,6 @@ - - - /** @file @publishedAll @@ -43,10 +40,15 @@ /** * Implementations of this method should fill the passed - * buffer with securely generated random data up to the - * current length, discarding any current contents. + * buffer with the generated pseudo-random data up to the + * current length, discarding any current contents. The + * implementations should leave with KErrNotSecure when + * the generated random data is not secure enough. * - * @param aDest The buffer in to which to write random data. + * @param aDest The buffer to fill with random data + * @leave KErrNotSecure Random data generated is not + * secure enough for crytographic operations + * otherwise, leaves with any other system wide error code. * */ virtual void GenerateBytesL(TDes8& aDest) = 0; @@ -59,20 +61,19 @@ /** * - * Sets a secure random number generator implementation to use - * for this thread. + * Sets a pseudo-random number generator implementation to use for this thread. * - * @param aRNG The secure random number generator to use. + * @param aRNG The pseudo-random number generator to use. * */ IMPORT_C void SetThreadRandomL(CRandom* aRNG); /** * - * Sets a secure random number generator implementation to use + * Sets a pseudo-random number generator implementation to use * for this thread, placing it on the cleanup stack. * - * @param aRNG The secure random number generator to use. + * @param aRNG The pseudo-random number generator to use. * */ IMPORT_C void SetThreadRandomLC(CRandom* aRNG); @@ -90,21 +91,24 @@ /** * - * Generates cryptographically secure random data, filling - * the provided buffer up to its current length, discarding - * any data that it may currently contain. + * Generates pseudo-random data. + * Fills the provided buffer up to its current length, + * discarding any data that it may currently contain. * * @param aDest The buffer to fill with random data + * @leave KErrNotSecure The random data generated is + * not secure enough for cryptographic operations + * otherwise, leaves with any other system wide error codes. * */ IMPORT_C void GenerateRandomBytesL(TDes8& aDest); +class CRandomShim; class CSystemRandom : public CRandom /** * - * This default secure random number generator uses - * system state to generate entropy for the generation - * of cryptographically secure random numbers. + * This default pseudo-random number generator uses system state + * to generate entropy for the generation of random numbers. * * @publishedAll * @released @@ -116,7 +120,7 @@ /** * - * Constructs a new system random number generator. + * Constructs a new pseudo-random number generator. * * @return A ready-to-use random number generator. */ @@ -124,7 +128,7 @@ /** * - * Constructs a new system random number generator, + * Constructs a new pseudo-random number generator, * and places it on the cleanup stack. * * @return A ready-to-use random number generator. @@ -134,26 +138,32 @@ /** * - * Implements the contract as specified in the base - * class, CRandom, filling the buffer supplied with - * cryptographically secure random data up to its - * current length, discarding its current content. + * Implements the contract as specified in the base class, CRandom, filling the buffer + * supplied with random data up to its current length, discarding its current content. + * It will leave with KErrNotSecure when the generated random data is not secure enough. * * @param aDest The buffer to which to write random data - * + * @leave KErrNotSecure The generated random data is not secure enough for cryptographic operations + * otherwise, leaves with any other system wide error codes. + * */ virtual void GenerateBytesL(TDes8& aDest); + + ~CSystemRandom(); private: CSystemRandom(void); CSystemRandom(const CSystemRandom&); CSystemRandom& operator=(const CSystemRandom&); + + void ConstructL(); + + CRandomShim *iShim; }; class TRandom /** * - * The user interface to the system cryptographically - * secure random number generator. + * The user interface to the random number generator. * * @publishedAll * @released @@ -163,8 +173,14 @@ /** * - * Fills the provided buffer with secure random data up to its - * current length, discarding any current content. + * Fills the provided buffer with pseudo-random data up to its current length, + * discarding any current content. + * + * This method will not return secure random numbers for some time after the phone boot-up. Because, + * pseudo-random number generator will take some time to attain a secure state by collecting enough + * entropy samples after the boot-up. Till that time, the pseudo-random numbers generated may not be + * cryptographically secure and there is no way to get to know about it with this API. + * So, if explcit notification on the strength of the random numbers is necessary, use TRandom::SecureRandomL. * * @param aDestination The buffer in which to write the random data. * @deprecated Use RandomL() instead @@ -173,16 +189,40 @@ */ IMPORT_C static void Random(TDes8& aDestination); - /** + /** * - * Fills the provided buffer with secure random data up to its - * current length, discarding any current content. + * Fills the provided buffer with pseudo-random data up to its current length, + * discarding any current content. + * + * This method will not return secure random numbers for some time after the phone boot-up. Because, + * pseudo-random number generator will take some time to attain a secure state by collecting enough + * entropy samples after the boot-up. Till that time, the pseudo-random numbers generated may not be + * cryptographically secure and there is no way to get to know about it with this API. + * So, if explcit notification on the strength of the random numbers is necessary, use TRandom::SecureRandomL. * * @param aDestination The buffer in which to write the random data. * @leave This function can leave under low memory conditions * */ IMPORT_C static void RandomL(TDes8& aDestination); + + /** + * + * Fills the provided buffer with the pseudo-random data up to its current length, discarding any current + * content of the descriptor. When this method returns normally (with out leave), the system state is secure + * and hence the random numbers generated are cryptographically secure as well. When this method leaves with + * the error code KErrNotSecure, the system internal state is not secure and hence the random numbers too. + * + * Though this method leaves when the system internal state is not secure, still the descriptor will be filled + * with pseudo-random bytes. This random data may or may not be secure enough. Recommended to treat these numbers + * as not secure. + * + * @param aDestination The buffer in which to write the random data. + * @leave KErrNotSecure The generated random numbers is not secure enough for cryptographic operations. + * Otherwise, leaves with some other system wide error codes. + * + */ + IMPORT_C static void SecureRandomL(TDes8& aDestination); }; class RRandomSession:public RSessionBase @@ -201,7 +241,7 @@ /** * - * Fills the provided buffer with secure random data up to its + * Fills the provided buffer with pseudo-random data up to its * current length, discarding any current content. * * @param aDestination The buffer in to which to write the random data @@ -211,7 +251,7 @@ /** * - * Opens a new session with the random number server. + * Opens a new session with the random number generator. * */ IMPORT_C void ConnectL(void);