1.1 --- a/epoc32/include/random.h Wed Mar 31 12:27:01 2010 +0100
1.2 +++ b/epoc32/include/random.h Wed Mar 31 12:33:34 2010 +0100
1.3 @@ -19,9 +19,6 @@
1.4
1.5
1.6
1.7 -
1.8 -
1.9 -
1.10 /**
1.11 @file
1.12 @publishedAll
1.13 @@ -43,10 +40,15 @@
1.14
1.15 /**
1.16 * Implementations of this method should fill the passed
1.17 - * buffer with securely generated random data up to the
1.18 - * current length, discarding any current contents.
1.19 + * buffer with the generated pseudo-random data up to the
1.20 + * current length, discarding any current contents. The
1.21 + * implementations should leave with KErrNotSecure when
1.22 + * the generated random data is not secure enough.
1.23 *
1.24 - * @param aDest The buffer in to which to write random data.
1.25 + * @param aDest The buffer to fill with random data
1.26 + * @leave KErrNotSecure Random data generated is not
1.27 + * secure enough for crytographic operations
1.28 + * otherwise, leaves with any other system wide error code.
1.29 *
1.30 */
1.31 virtual void GenerateBytesL(TDes8& aDest) = 0;
1.32 @@ -59,20 +61,19 @@
1.33
1.34 /**
1.35 *
1.36 - * Sets a secure random number generator implementation to use
1.37 - * for this thread.
1.38 + * Sets a pseudo-random number generator implementation to use for this thread.
1.39 *
1.40 - * @param aRNG The secure random number generator to use.
1.41 + * @param aRNG The pseudo-random number generator to use.
1.42 *
1.43 */
1.44 IMPORT_C void SetThreadRandomL(CRandom* aRNG);
1.45
1.46 /**
1.47 *
1.48 - * Sets a secure random number generator implementation to use
1.49 + * Sets a pseudo-random number generator implementation to use
1.50 * for this thread, placing it on the cleanup stack.
1.51 *
1.52 - * @param aRNG The secure random number generator to use.
1.53 + * @param aRNG The pseudo-random number generator to use.
1.54 *
1.55 */
1.56 IMPORT_C void SetThreadRandomLC(CRandom* aRNG);
1.57 @@ -90,21 +91,24 @@
1.58
1.59 /**
1.60 *
1.61 - * Generates cryptographically secure random data, filling
1.62 - * the provided buffer up to its current length, discarding
1.63 - * any data that it may currently contain.
1.64 + * Generates pseudo-random data.
1.65 + * Fills the provided buffer up to its current length,
1.66 + * discarding any data that it may currently contain.
1.67 *
1.68 * @param aDest The buffer to fill with random data
1.69 + * @leave KErrNotSecure The random data generated is
1.70 + * not secure enough for cryptographic operations
1.71 + * otherwise, leaves with any other system wide error codes.
1.72 *
1.73 */
1.74 IMPORT_C void GenerateRandomBytesL(TDes8& aDest);
1.75
1.76 +class CRandomShim;
1.77 class CSystemRandom : public CRandom
1.78 /**
1.79 *
1.80 - * This default secure random number generator uses
1.81 - * system state to generate entropy for the generation
1.82 - * of cryptographically secure random numbers.
1.83 + * This default pseudo-random number generator uses system state
1.84 + * to generate entropy for the generation of random numbers.
1.85 *
1.86 * @publishedAll
1.87 * @released
1.88 @@ -116,7 +120,7 @@
1.89
1.90 /**
1.91 *
1.92 - * Constructs a new system random number generator.
1.93 + * Constructs a new pseudo-random number generator.
1.94 *
1.95 * @return A ready-to-use random number generator.
1.96 */
1.97 @@ -124,7 +128,7 @@
1.98
1.99 /**
1.100 *
1.101 - * Constructs a new system random number generator,
1.102 + * Constructs a new pseudo-random number generator,
1.103 * and places it on the cleanup stack.
1.104 *
1.105 * @return A ready-to-use random number generator.
1.106 @@ -134,26 +138,32 @@
1.107
1.108 /**
1.109 *
1.110 - * Implements the contract as specified in the base
1.111 - * class, CRandom, filling the buffer supplied with
1.112 - * cryptographically secure random data up to its
1.113 - * current length, discarding its current content.
1.114 + * Implements the contract as specified in the base class, CRandom, filling the buffer
1.115 + * supplied with random data up to its current length, discarding its current content.
1.116 + * It will leave with KErrNotSecure when the generated random data is not secure enough.
1.117 *
1.118 * @param aDest The buffer to which to write random data
1.119 - *
1.120 + * @leave KErrNotSecure The generated random data is not secure enough for cryptographic operations
1.121 + * otherwise, leaves with any other system wide error codes.
1.122 + *
1.123 */
1.124 virtual void GenerateBytesL(TDes8& aDest);
1.125 +
1.126 + ~CSystemRandom();
1.127 private:
1.128 CSystemRandom(void);
1.129 CSystemRandom(const CSystemRandom&);
1.130 CSystemRandom& operator=(const CSystemRandom&);
1.131 +
1.132 + void ConstructL();
1.133 +
1.134 + CRandomShim *iShim;
1.135 };
1.136
1.137 class TRandom
1.138 /**
1.139 *
1.140 - * The user interface to the system cryptographically
1.141 - * secure random number generator.
1.142 + * The user interface to the random number generator.
1.143 *
1.144 * @publishedAll
1.145 * @released
1.146 @@ -163,8 +173,14 @@
1.147
1.148 /**
1.149 *
1.150 - * Fills the provided buffer with secure random data up to its
1.151 - * current length, discarding any current content.
1.152 + * Fills the provided buffer with pseudo-random data up to its current length,
1.153 + * discarding any current content.
1.154 + *
1.155 + * This method will not return secure random numbers for some time after the phone boot-up. Because,
1.156 + * pseudo-random number generator will take some time to attain a secure state by collecting enough
1.157 + * entropy samples after the boot-up. Till that time, the pseudo-random numbers generated may not be
1.158 + * cryptographically secure and there is no way to get to know about it with this API.
1.159 + * So, if explcit notification on the strength of the random numbers is necessary, use TRandom::SecureRandomL.
1.160 *
1.161 * @param aDestination The buffer in which to write the random data.
1.162 * @deprecated Use RandomL() instead
1.163 @@ -173,16 +189,40 @@
1.164 */
1.165 IMPORT_C static void Random(TDes8& aDestination);
1.166
1.167 - /**
1.168 + /**
1.169 *
1.170 - * Fills the provided buffer with secure random data up to its
1.171 - * current length, discarding any current content.
1.172 + * Fills the provided buffer with pseudo-random data up to its current length,
1.173 + * discarding any current content.
1.174 + *
1.175 + * This method will not return secure random numbers for some time after the phone boot-up. Because,
1.176 + * pseudo-random number generator will take some time to attain a secure state by collecting enough
1.177 + * entropy samples after the boot-up. Till that time, the pseudo-random numbers generated may not be
1.178 + * cryptographically secure and there is no way to get to know about it with this API.
1.179 + * So, if explcit notification on the strength of the random numbers is necessary, use TRandom::SecureRandomL.
1.180 *
1.181 * @param aDestination The buffer in which to write the random data.
1.182 * @leave This function can leave under low memory conditions
1.183 *
1.184 */
1.185 IMPORT_C static void RandomL(TDes8& aDestination);
1.186 +
1.187 + /**
1.188 + *
1.189 + * Fills the provided buffer with the pseudo-random data up to its current length, discarding any current
1.190 + * content of the descriptor. When this method returns normally (with out leave), the system state is secure
1.191 + * and hence the random numbers generated are cryptographically secure as well. When this method leaves with
1.192 + * the error code KErrNotSecure, the system internal state is not secure and hence the random numbers too.
1.193 + *
1.194 + * Though this method leaves when the system internal state is not secure, still the descriptor will be filled
1.195 + * with pseudo-random bytes. This random data may or may not be secure enough. Recommended to treat these numbers
1.196 + * as not secure.
1.197 + *
1.198 + * @param aDestination The buffer in which to write the random data.
1.199 + * @leave KErrNotSecure The generated random numbers is not secure enough for cryptographic operations.
1.200 + * Otherwise, leaves with some other system wide error codes.
1.201 + *
1.202 + */
1.203 + IMPORT_C static void SecureRandomL(TDes8& aDestination);
1.204 };
1.205
1.206 class RRandomSession:public RSessionBase
1.207 @@ -201,7 +241,7 @@
1.208
1.209 /**
1.210 *
1.211 - * Fills the provided buffer with secure random data up to its
1.212 + * Fills the provided buffer with pseudo-random data up to its
1.213 * current length, discarding any current content.
1.214 *
1.215 * @param aDestination The buffer in to which to write the random data
1.216 @@ -211,7 +251,7 @@
1.217
1.218 /**
1.219 *
1.220 - * Opens a new session with the random number server.
1.221 + * Opens a new session with the random number generator.
1.222 *
1.223 */
1.224 IMPORT_C void ConnectL(void);