88 */ |
89 */ |
89 IMPORT_C void DestroyThreadRandom(void); |
90 IMPORT_C void DestroyThreadRandom(void); |
90 |
91 |
91 /** |
92 /** |
92 * |
93 * |
93 * Generates cryptographically secure random data, filling |
94 * Generates pseudo-random data. |
94 * the provided buffer up to its current length, discarding |
95 * Fills the provided buffer up to its current length, |
95 * any data that it may currently contain. |
96 * discarding any data that it may currently contain. |
96 * |
97 * |
97 * @param aDest The buffer to fill with random data |
98 * @param aDest The buffer to fill with random data |
|
99 * @leave KErrNotSecure The random data generated is |
|
100 * not secure enough for cryptographic operations |
|
101 * otherwise, leaves with any other system wide error codes. |
98 * |
102 * |
99 */ |
103 */ |
100 IMPORT_C void GenerateRandomBytesL(TDes8& aDest); |
104 IMPORT_C void GenerateRandomBytesL(TDes8& aDest); |
101 |
105 |
|
106 class CRandomShim; |
102 class CSystemRandom : public CRandom |
107 class CSystemRandom : public CRandom |
103 /** |
108 /** |
104 * |
109 * |
105 * This default secure random number generator uses |
110 * This default pseudo-random number generator uses system state |
106 * system state to generate entropy for the generation |
111 * to generate entropy for the generation of random numbers. |
107 * of cryptographically secure random numbers. |
112 * |
108 * |
113 * @publishedAll |
109 * @publishedAll |
114 * @released |
110 * @released |
115 * |
111 * |
116 */ |
112 */ |
117 |
113 |
118 { |
114 { |
119 public: |
115 public: |
120 |
116 |
121 /** |
117 /** |
122 * |
118 * |
123 * Constructs a new pseudo-random number generator. |
119 * Constructs a new system random number generator. |
|
120 * |
124 * |
121 * @return A ready-to-use random number generator. |
125 * @return A ready-to-use random number generator. |
122 */ |
126 */ |
123 IMPORT_C static CSystemRandom* NewL(void); |
127 IMPORT_C static CSystemRandom* NewL(void); |
124 |
128 |
125 /** |
129 /** |
126 * |
130 * |
127 * Constructs a new system random number generator, |
131 * Constructs a new pseudo-random number generator, |
128 * and places it on the cleanup stack. |
132 * and places it on the cleanup stack. |
129 * |
133 * |
130 * @return A ready-to-use random number generator. |
134 * @return A ready-to-use random number generator. |
131 * |
135 * |
132 */ |
136 */ |
133 IMPORT_C static CSystemRandom* NewLC(void); |
137 IMPORT_C static CSystemRandom* NewLC(void); |
134 |
138 |
135 /** |
139 /** |
136 * |
140 * |
137 * Implements the contract as specified in the base |
141 * Implements the contract as specified in the base class, CRandom, filling the buffer |
138 * class, CRandom, filling the buffer supplied with |
142 * supplied with random data up to its current length, discarding its current content. |
139 * cryptographically secure random data up to its |
143 * It will leave with KErrNotSecure when the generated random data is not secure enough. |
140 * current length, discarding its current content. |
|
141 * |
144 * |
142 * @param aDest The buffer to which to write random data |
145 * @param aDest The buffer to which to write random data |
143 * |
146 * @leave KErrNotSecure The generated random data is not secure enough for cryptographic operations |
|
147 * otherwise, leaves with any other system wide error codes. |
|
148 * |
144 */ |
149 */ |
145 virtual void GenerateBytesL(TDes8& aDest); |
150 virtual void GenerateBytesL(TDes8& aDest); |
|
151 |
|
152 ~CSystemRandom(); |
146 private: |
153 private: |
147 CSystemRandom(void); |
154 CSystemRandom(void); |
148 CSystemRandom(const CSystemRandom&); |
155 CSystemRandom(const CSystemRandom&); |
149 CSystemRandom& operator=(const CSystemRandom&); |
156 CSystemRandom& operator=(const CSystemRandom&); |
|
157 |
|
158 void ConstructL(); |
|
159 |
|
160 CRandomShim *iShim; |
150 }; |
161 }; |
151 |
162 |
152 class TRandom |
163 class TRandom |
153 /** |
164 /** |
154 * |
165 * |
155 * The user interface to the system cryptographically |
166 * The user interface to the random number generator. |
156 * secure random number generator. |
167 * |
157 * |
168 * @publishedAll |
158 * @publishedAll |
169 * @released |
159 * @released |
170 */ |
160 */ |
171 { |
161 { |
172 public: |
162 public: |
173 |
163 |
174 /** |
164 /** |
175 * |
165 * |
176 * Fills the provided buffer with pseudo-random data up to its current length, |
166 * Fills the provided buffer with secure random data up to its |
177 * discarding any current content. |
167 * current length, discarding any current content. |
178 * |
|
179 * This method will not return secure random numbers for some time after the phone boot-up. Because, |
|
180 * pseudo-random number generator will take some time to attain a secure state by collecting enough |
|
181 * entropy samples after the boot-up. Till that time, the pseudo-random numbers generated may not be |
|
182 * cryptographically secure and there is no way to get to know about it with this API. |
|
183 * So, if explcit notification on the strength of the random numbers is necessary, use TRandom::SecureRandomL. |
168 * |
184 * |
169 * @param aDestination The buffer in which to write the random data. |
185 * @param aDestination The buffer in which to write the random data. |
170 * @deprecated Use RandomL() instead |
186 * @deprecated Use RandomL() instead |
171 * @panic This function can panic under low memory conditions |
187 * @panic This function can panic under low memory conditions |
172 * |
188 * |
173 */ |
189 */ |
174 IMPORT_C static void Random(TDes8& aDestination); |
190 IMPORT_C static void Random(TDes8& aDestination); |
175 |
191 |
176 /** |
192 /** |
177 * |
193 * |
178 * Fills the provided buffer with secure random data up to its |
194 * Fills the provided buffer with pseudo-random data up to its current length, |
179 * current length, discarding any current content. |
195 * discarding any current content. |
|
196 * |
|
197 * This method will not return secure random numbers for some time after the phone boot-up. Because, |
|
198 * pseudo-random number generator will take some time to attain a secure state by collecting enough |
|
199 * entropy samples after the boot-up. Till that time, the pseudo-random numbers generated may not be |
|
200 * cryptographically secure and there is no way to get to know about it with this API. |
|
201 * So, if explcit notification on the strength of the random numbers is necessary, use TRandom::SecureRandomL. |
180 * |
202 * |
181 * @param aDestination The buffer in which to write the random data. |
203 * @param aDestination The buffer in which to write the random data. |
182 * @leave This function can leave under low memory conditions |
204 * @leave This function can leave under low memory conditions |
183 * |
205 * |
184 */ |
206 */ |
185 IMPORT_C static void RandomL(TDes8& aDestination); |
207 IMPORT_C static void RandomL(TDes8& aDestination); |
|
208 |
|
209 /** |
|
210 * |
|
211 * Fills the provided buffer with the pseudo-random data up to its current length, discarding any current |
|
212 * content of the descriptor. When this method returns normally (with out leave), the system state is secure |
|
213 * and hence the random numbers generated are cryptographically secure as well. When this method leaves with |
|
214 * the error code KErrNotSecure, the system internal state is not secure and hence the random numbers too. |
|
215 * |
|
216 * Though this method leaves when the system internal state is not secure, still the descriptor will be filled |
|
217 * with pseudo-random bytes. This random data may or may not be secure enough. Recommended to treat these numbers |
|
218 * as not secure. |
|
219 * |
|
220 * @param aDestination The buffer in which to write the random data. |
|
221 * @leave KErrNotSecure The generated random numbers is not secure enough for cryptographic operations. |
|
222 * Otherwise, leaves with some other system wide error codes. |
|
223 * |
|
224 */ |
|
225 IMPORT_C static void SecureRandomL(TDes8& aDestination); |
186 }; |
226 }; |
187 |
227 |
188 class RRandomSession:public RSessionBase |
228 class RRandomSession:public RSessionBase |
189 /** |
229 /** |
190 * |
230 * |