38 { |
38 { |
39 public: |
39 public: |
40 |
40 |
41 /** |
41 /** |
42 * Implementations of this method should fill the passed |
42 * Implementations of this method should fill the passed |
43 * buffer with securely generated random data up to the |
43 * buffer with the generated pseudo-random data up to the |
44 * current length, discarding any current contents. |
44 * current length, discarding any current contents. The |
45 * |
45 * implementations should leave with KErrNotSecure when |
46 * @param aDest The buffer in to which to write random data. |
46 * the generated random data is not secure enough. |
|
47 * |
|
48 * @param aDest The buffer to fill with random data |
|
49 * @leave KErrNotSecure Random data generated is not |
|
50 * secure enough for crytographic operations |
|
51 * otherwise, leaves with any other system wide error code. |
47 * |
52 * |
48 */ |
53 */ |
49 virtual void GenerateBytesL(TDes8& aDest) = 0; |
54 virtual void GenerateBytesL(TDes8& aDest) = 0; |
50 protected: |
55 protected: |
51 IMPORT_C CRandom(void); |
56 IMPORT_C CRandom(void); |
54 CRandom& operator=(const CRandom&); |
59 CRandom& operator=(const CRandom&); |
55 }; |
60 }; |
56 |
61 |
57 /** |
62 /** |
58 * |
63 * |
59 * Sets a secure random number generator implementation to use |
64 * Sets a pseudo-random number generator implementation to use for this thread. |
60 * for this thread. |
|
61 * |
65 * |
62 * @param aRNG The secure random number generator to use. |
66 * @param aRNG The pseudo-random number generator to use. |
63 * |
67 * |
64 */ |
68 */ |
65 IMPORT_C void SetThreadRandomL(CRandom* aRNG); |
69 IMPORT_C void SetThreadRandomL(CRandom* aRNG); |
66 |
70 |
67 /** |
71 /** |
68 * |
72 * |
69 * Sets a secure random number generator implementation to use |
73 * Sets a pseudo-random number generator implementation to use |
70 * for this thread, placing it on the cleanup stack. |
74 * for this thread, placing it on the cleanup stack. |
71 * |
75 * |
72 * @param aRNG The secure random number generator to use. |
76 * @param aRNG The pseudo-random number generator to use. |
73 * |
77 * |
74 */ |
78 */ |
75 IMPORT_C void SetThreadRandomLC(CRandom* aRNG); |
79 IMPORT_C void SetThreadRandomLC(CRandom* aRNG); |
76 |
80 |
77 /** @internalAll */ |
81 /** @internalAll */ |
85 */ |
89 */ |
86 IMPORT_C void DestroyThreadRandom(void); |
90 IMPORT_C void DestroyThreadRandom(void); |
87 |
91 |
88 /** |
92 /** |
89 * |
93 * |
90 * Generates cryptographically secure random data, filling |
94 * Generates pseudo-random data. |
91 * the provided buffer up to its current length, discarding |
95 * Fills the provided buffer up to its current length, |
92 * any data that it may currently contain. |
96 * discarding any data that it may currently contain. |
93 * |
97 * |
94 * @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. |
95 * |
102 * |
96 */ |
103 */ |
97 IMPORT_C void GenerateRandomBytesL(TDes8& aDest); |
104 IMPORT_C void GenerateRandomBytesL(TDes8& aDest); |
98 |
105 |
99 class CRandomShim; |
106 class CRandomShim; |
100 class CSystemRandom : public CRandom |
107 class CSystemRandom : public CRandom |
101 /** |
108 /** |
102 * |
109 * |
103 * This default secure random number generator uses |
110 * This default pseudo-random number generator uses system state |
104 * system state to generate entropy for the generation |
111 * to generate entropy for the generation of random numbers. |
105 * of cryptographically secure random numbers. |
112 * |
106 * |
113 * @publishedAll |
107 * @publishedAll |
114 * @released |
108 * @released |
115 * |
109 * |
116 */ |
110 */ |
117 |
111 |
118 { |
112 { |
119 public: |
113 public: |
120 |
114 |
121 /** |
115 /** |
122 * |
116 * |
123 * Constructs a new pseudo-random number generator. |
117 * Constructs a new system random number generator. |
|
118 * |
124 * |
119 * @return A ready-to-use random number generator. |
125 * @return A ready-to-use random number generator. |
120 */ |
126 */ |
121 IMPORT_C static CSystemRandom* NewL(void); |
127 IMPORT_C static CSystemRandom* NewL(void); |
122 |
128 |
123 /** |
129 /** |
124 * |
130 * |
125 * Constructs a new system random number generator, |
131 * Constructs a new pseudo-random number generator, |
126 * and places it on the cleanup stack. |
132 * and places it on the cleanup stack. |
127 * |
133 * |
128 * @return A ready-to-use random number generator. |
134 * @return A ready-to-use random number generator. |
129 * |
135 * |
130 */ |
136 */ |
131 IMPORT_C static CSystemRandom* NewLC(void); |
137 IMPORT_C static CSystemRandom* NewLC(void); |
132 |
138 |
133 /** |
139 /** |
134 * |
140 * |
135 * Implements the contract as specified in the base |
141 * Implements the contract as specified in the base class, CRandom, filling the buffer |
136 * class, CRandom, filling the buffer supplied with |
142 * supplied with random data up to its current length, discarding its current content. |
137 * cryptographically secure random data up to its |
143 * It will leave with KErrNotSecure when the generated random data is not secure enough. |
138 * current length, discarding its current content. |
|
139 * |
144 * |
140 * @param aDest The buffer to which to write random data |
145 * @param aDest The buffer to which to write random data |
141 * |
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 * |
142 */ |
149 */ |
143 virtual void GenerateBytesL(TDes8& aDest); |
150 virtual void GenerateBytesL(TDes8& aDest); |
144 |
151 |
145 ~CSystemRandom(); |
152 ~CSystemRandom(); |
146 private: |
153 private: |
154 }; |
161 }; |
155 |
162 |
156 class TRandom |
163 class TRandom |
157 /** |
164 /** |
158 * |
165 * |
159 * The user interface to the system cryptographically |
166 * The user interface to the random number generator. |
160 * secure random number generator. |
167 * |
161 * |
168 * @publishedAll |
162 * @publishedAll |
169 * @released |
163 * @released |
170 */ |
164 */ |
171 { |
165 { |
172 public: |
166 public: |
173 |
167 |
174 /** |
168 /** |
175 * |
169 * |
176 * Fills the provided buffer with pseudo-random data up to its current length, |
170 * Fills the provided buffer with secure random data up to its |
177 * discarding any current content. |
171 * 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. |
172 * |
184 * |
173 * @param aDestination The buffer in which to write the random data. |
185 * @param aDestination The buffer in which to write the random data. |
174 * @deprecated Use RandomL() instead |
186 * @deprecated Use RandomL() instead |
175 * @panic This function can panic under low memory conditions |
187 * @panic This function can panic under low memory conditions |
176 * |
188 * |
177 */ |
189 */ |
178 IMPORT_C static void Random(TDes8& aDestination); |
190 IMPORT_C static void Random(TDes8& aDestination); |
179 |
191 |
180 /** |
192 /** |
181 * |
193 * |
182 * 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, |
183 * 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. |
184 * |
202 * |
185 * @param aDestination The buffer in which to write the random data. |
203 * @param aDestination The buffer in which to write the random data. |
186 * @leave This function can leave under low memory conditions |
204 * @leave This function can leave under low memory conditions |
187 * |
205 * |
188 */ |
206 */ |
189 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); |
190 }; |
226 }; |
191 |
227 |
192 class RRandomSession:public RSessionBase |
228 class RRandomSession:public RSessionBase |
193 /** |
229 /** |
194 * |
230 * |
203 |
239 |
204 IMPORT_C RRandomSession(void); |
240 IMPORT_C RRandomSession(void); |
205 |
241 |
206 /** |
242 /** |
207 * |
243 * |
208 * Fills the provided buffer with secure random data up to its |
244 * Fills the provided buffer with pseudo-random data up to its |
209 * current length, discarding any current content. |
245 * current length, discarding any current content. |
210 * |
246 * |
211 * @param aDestination The buffer in to which to write the random data |
247 * @param aDestination The buffer in to which to write the random data |
212 * |
248 * |
213 */ |
249 */ |
214 IMPORT_C TInt GetRandom(TDes8& aDestination); |
250 IMPORT_C TInt GetRandom(TDes8& aDestination); |
215 |
251 |
216 /** |
252 /** |
217 * |
253 * |
218 * Opens a new session with the random number server. |
254 * Opens a new session with the random number generator. |
219 * |
255 * |
220 */ |
256 */ |
221 IMPORT_C void ConnectL(void); |
257 IMPORT_C void ConnectL(void); |
222 }; |
258 }; |
223 |
259 |