1 | /* |
2 | * Copyright 1995-2018 The OpenSSL Project Authors. All Rights Reserved. |
3 | * |
4 | * Licensed under the Apache License 2.0 (the "License"). You may not use |
5 | * this file except in compliance with the License. You can obtain a copy |
6 | * in the file LICENSE in the source distribution or at |
7 | * https://www.openssl.org/source/license.html |
8 | */ |
9 | |
10 | #ifndef OSSL_CRYPTO_RAND_LOCAL_H |
11 | # define OSSL_CRYPTO_RAND_LOCAL_H |
12 | |
13 | # include <openssl/aes.h> |
14 | # include <openssl/evp.h> |
15 | # include <openssl/sha.h> |
16 | # include <openssl/hmac.h> |
17 | # include <openssl/ec.h> |
18 | # include <openssl/rand_drbg.h> |
19 | # include "internal/tsan_assist.h" |
20 | # include "crypto/rand.h" |
21 | |
22 | # include "internal/numbers.h" |
23 | |
24 | /* How many times to read the TSC as a randomness source. */ |
25 | # define TSC_READ_COUNT 4 |
26 | |
27 | /* Maximum reseed intervals */ |
28 | # define MAX_RESEED_INTERVAL (1 << 24) |
29 | # define MAX_RESEED_TIME_INTERVAL (1 << 20) /* approx. 12 days */ |
30 | |
31 | /* Default reseed intervals */ |
32 | # define MASTER_RESEED_INTERVAL (1 << 8) |
33 | # define SLAVE_RESEED_INTERVAL (1 << 16) |
34 | # define MASTER_RESEED_TIME_INTERVAL (60*60) /* 1 hour */ |
35 | # define SLAVE_RESEED_TIME_INTERVAL (7*60) /* 7 minutes */ |
36 | |
37 | /* |
38 | * The number of bytes that constitutes an atomic lump of entropy with respect |
39 | * to the FIPS 140-2 section 4.9.2 Conditional Tests. The size is somewhat |
40 | * arbitrary, the smaller the value, the less entropy is consumed on first |
41 | * read but the higher the probability of the test failing by accident. |
42 | * |
43 | * The value is in bytes. |
44 | */ |
45 | #define CRNGT_BUFSIZ 16 |
46 | |
47 | /* |
48 | * Maximum input size for the DRBG (entropy, nonce, personalization string) |
49 | * |
50 | * NIST SP800 90Ar1 allows a maximum of (1 << 35) bits i.e., (1 << 32) bytes. |
51 | * |
52 | * We lower it to 'only' INT32_MAX bytes, which is equivalent to 2 gigabytes. |
53 | */ |
54 | # define DRBG_MAX_LENGTH INT32_MAX |
55 | |
56 | /* The default nonce */ |
57 | #ifdef CHARSET_EBCDIC |
58 | # define DRBG_DEFAULT_PERS_STRING { 0x4f, 0x70, 0x65, 0x6e, 0x53, 0x53, \ |
59 | 0x4c, 0x20, 0x4e, 0x49, 0x53, 0x54, 0x20, 0x53, 0x50, 0x20, 0x38, 0x30, \ |
60 | 0x30, 0x2d, 0x39, 0x30, 0x41, 0x20, 0x44, 0x52, 0x42, 0x47, 0x00}; |
61 | #else |
62 | # define DRBG_DEFAULT_PERS_STRING "OpenSSL NIST SP 800-90A DRBG" |
63 | #endif |
64 | |
65 | /* |
66 | * Maximum allocation size for RANDOM_POOL buffers |
67 | * |
68 | * The max_len value for the buffer provided to the rand_drbg_get_entropy() |
69 | * callback is currently 2^31 bytes (2 gigabytes), if a derivation function |
70 | * is used. Since this is much too large to be allocated, the rand_pool_new() |
71 | * function chooses more modest values as default pool length, bounded |
72 | * by RAND_POOL_MIN_LENGTH and RAND_POOL_MAX_LENGTH |
73 | * |
74 | * The choice of the RAND_POOL_FACTOR is large enough such that the |
75 | * RAND_POOL can store a random input which has a lousy entropy rate of |
76 | * 8/256 (= 0.03125) bits per byte. This input will be sent through the |
77 | * derivation function which 'compresses' the low quality input into a |
78 | * high quality output. |
79 | * |
80 | * The factor 1.5 below is the pessimistic estimate for the extra amount |
81 | * of entropy required when no get_nonce() callback is defined. |
82 | */ |
83 | # define RAND_POOL_FACTOR 256 |
84 | # define RAND_POOL_MAX_LENGTH (RAND_POOL_FACTOR * \ |
85 | 3 * (RAND_DRBG_STRENGTH / 16)) |
86 | /* |
87 | * = (RAND_POOL_FACTOR * \ |
88 | * 1.5 * (RAND_DRBG_STRENGTH / 8)) |
89 | */ |
90 | |
91 | /* |
92 | * Initial allocation minimum. |
93 | * |
94 | * There is a distinction between the secure and normal allocation minimums. |
95 | * Ideally, the secure allocation size should be a power of two. The normal |
96 | * allocation size doesn't have any such restriction. |
97 | * |
98 | * The secure value is based on 128 bits of secure material, which is 16 bytes. |
99 | * Typically, the DRBGs will set a minimum larger than this so optimal |
100 | * allocation ought to take place (for full quality seed material). |
101 | * |
102 | * The normal value has been chosed by noticing that the rand_drbg_get_nonce |
103 | * function is usually the largest of the built in allocation (twenty four |
104 | * bytes and then appending another sixteen bytes). This means the buffer ends |
105 | * with 40 bytes. The value of forty eight is comfortably above this which |
106 | * allows some slack in the platform specific values used. |
107 | */ |
108 | # define RAND_POOL_MIN_ALLOCATION(secure) ((secure) ? 16 : 48) |
109 | |
110 | /* DRBG status values */ |
111 | typedef enum drbg_status_e { |
112 | DRBG_UNINITIALISED, |
113 | DRBG_READY, |
114 | DRBG_ERROR |
115 | } DRBG_STATUS; |
116 | |
117 | |
118 | /* instantiate */ |
119 | typedef int (*RAND_DRBG_instantiate_fn)(RAND_DRBG *ctx, |
120 | const unsigned char *ent, |
121 | size_t entlen, |
122 | const unsigned char *nonce, |
123 | size_t noncelen, |
124 | const unsigned char *pers, |
125 | size_t perslen); |
126 | /* reseed */ |
127 | typedef int (*RAND_DRBG_reseed_fn)(RAND_DRBG *ctx, |
128 | const unsigned char *ent, |
129 | size_t entlen, |
130 | const unsigned char *adin, |
131 | size_t adinlen); |
132 | /* generate output */ |
133 | typedef int (*RAND_DRBG_generate_fn)(RAND_DRBG *ctx, |
134 | unsigned char *out, |
135 | size_t outlen, |
136 | const unsigned char *adin, |
137 | size_t adinlen); |
138 | /* uninstantiate */ |
139 | typedef int (*RAND_DRBG_uninstantiate_fn)(RAND_DRBG *ctx); |
140 | |
141 | |
142 | /* |
143 | * The DRBG methods |
144 | */ |
145 | |
146 | typedef struct rand_drbg_method_st { |
147 | RAND_DRBG_instantiate_fn instantiate; |
148 | RAND_DRBG_reseed_fn reseed; |
149 | RAND_DRBG_generate_fn generate; |
150 | RAND_DRBG_uninstantiate_fn uninstantiate; |
151 | } RAND_DRBG_METHOD; |
152 | |
153 | /* 888 bits from SP800-90Ar1 10.1 table 2 */ |
154 | #define HASH_PRNG_MAX_SEEDLEN (888/8) |
155 | |
156 | typedef struct rand_drbg_hash_st { |
157 | EVP_MD *md; |
158 | EVP_MD_CTX *ctx; |
159 | size_t blocklen; |
160 | unsigned char V[HASH_PRNG_MAX_SEEDLEN]; |
161 | unsigned char C[HASH_PRNG_MAX_SEEDLEN]; |
162 | /* Temporary value storage: should always exceed max digest length */ |
163 | unsigned char vtmp[HASH_PRNG_MAX_SEEDLEN]; |
164 | } RAND_DRBG_HASH; |
165 | |
166 | typedef struct rand_drbg_hmac_st { |
167 | EVP_MD *md; |
168 | HMAC_CTX *ctx; |
169 | size_t blocklen; |
170 | unsigned char K[EVP_MAX_MD_SIZE]; |
171 | unsigned char V[EVP_MAX_MD_SIZE]; |
172 | } RAND_DRBG_HMAC; |
173 | |
174 | /* |
175 | * The state of a DRBG AES-CTR. |
176 | */ |
177 | typedef struct rand_drbg_ctr_st { |
178 | EVP_CIPHER_CTX *ctx; |
179 | EVP_CIPHER_CTX *ctx_df; |
180 | EVP_CIPHER *cipher; |
181 | size_t keylen; |
182 | unsigned char K[32]; |
183 | unsigned char V[16]; |
184 | /* Temporary block storage used by ctr_df */ |
185 | unsigned char bltmp[16]; |
186 | size_t bltmp_pos; |
187 | unsigned char KX[48]; |
188 | } RAND_DRBG_CTR; |
189 | |
190 | |
191 | /* |
192 | * The 'random pool' acts as a dumb container for collecting random |
193 | * input from various entropy sources. The pool has no knowledge about |
194 | * whether its randomness is fed into a legacy RAND_METHOD via RAND_add() |
195 | * or into a new style RAND_DRBG. It is the callers duty to 1) initialize the |
196 | * random pool, 2) pass it to the polling callbacks, 3) seed the RNG, and |
197 | * 4) cleanup the random pool again. |
198 | * |
199 | * The random pool contains no locking mechanism because its scope and |
200 | * lifetime is intended to be restricted to a single stack frame. |
201 | */ |
202 | struct rand_pool_st { |
203 | unsigned char *buffer; /* points to the beginning of the random pool */ |
204 | size_t len; /* current number of random bytes contained in the pool */ |
205 | |
206 | int attached; /* true pool was attached to existing buffer */ |
207 | int secure; /* 1: allocated on the secure heap, 0: otherwise */ |
208 | |
209 | size_t min_len; /* minimum number of random bytes requested */ |
210 | size_t max_len; /* maximum number of random bytes (allocated buffer size) */ |
211 | size_t alloc_len; /* current number of bytes allocated */ |
212 | size_t entropy; /* current entropy count in bits */ |
213 | size_t entropy_requested; /* requested entropy count in bits */ |
214 | }; |
215 | |
216 | /* |
217 | * The state of all types of DRBGs, even though we only have CTR mode |
218 | * right now. |
219 | */ |
220 | struct rand_drbg_st { |
221 | CRYPTO_RWLOCK *lock; |
222 | /* The library context this DRBG is associated with, if any */ |
223 | OPENSSL_CTX *libctx; |
224 | RAND_DRBG *parent; |
225 | int secure; /* 1: allocated on the secure heap, 0: otherwise */ |
226 | int type; /* the nid of the underlying algorithm */ |
227 | /* |
228 | * Stores the return value of openssl_get_fork_id() as of when we last |
229 | * reseeded. The DRBG reseeds automatically whenever drbg->fork_id != |
230 | * openssl_get_fork_id(). Used to provide fork-safety and reseed this |
231 | * DRBG in the child process. |
232 | */ |
233 | int fork_id; |
234 | unsigned short flags; /* various external flags */ |
235 | |
236 | /* |
237 | * The random_data is used by RAND_add()/drbg_add() to attach random |
238 | * data to the global drbg, such that the rand_drbg_get_entropy() callback |
239 | * can pull it during instantiation and reseeding. This is necessary to |
240 | * reconcile the different philosophies of the RAND and the RAND_DRBG |
241 | * with respect to how randomness is added to the RNG during reseeding |
242 | * (see PR #4328). |
243 | */ |
244 | struct rand_pool_st *seed_pool; |
245 | |
246 | /* |
247 | * Auxiliary pool for additional data. |
248 | */ |
249 | struct rand_pool_st *adin_pool; |
250 | |
251 | /* |
252 | * The following parameters are setup by the per-type "init" function. |
253 | * |
254 | * The supported types and their init functions are: |
255 | * (1) CTR_DRBG: drbg_ctr_init(). |
256 | * (2) HMAC_DRBG: drbg_hmac_init(). |
257 | * (3) HASH_DRBG: drbg_hash_init(). |
258 | * |
259 | * The parameters are closely related to the ones described in |
260 | * section '10.2.1 CTR_DRBG' of [NIST SP 800-90Ar1], with one |
261 | * crucial difference: In the NIST standard, all counts are given |
262 | * in bits, whereas in OpenSSL entropy counts are given in bits |
263 | * and buffer lengths are given in bytes. |
264 | * |
265 | * Since this difference has lead to some confusion in the past, |
266 | * (see [GitHub Issue #2443], formerly [rt.openssl.org #4055]) |
267 | * the 'len' suffix has been added to all buffer sizes for |
268 | * clarification. |
269 | */ |
270 | |
271 | int strength; |
272 | size_t max_request; |
273 | size_t min_entropylen, max_entropylen; |
274 | size_t min_noncelen, max_noncelen; |
275 | size_t max_perslen, max_adinlen; |
276 | |
277 | /* |
278 | * Counts the number of generate requests since the last reseed |
279 | * (Starts at 1). This value is the reseed_counter as defined in |
280 | * NIST SP 800-90Ar1 |
281 | */ |
282 | unsigned int reseed_gen_counter; |
283 | /* |
284 | * Maximum number of generate requests until a reseed is required. |
285 | * This value is ignored if it is zero. |
286 | */ |
287 | unsigned int reseed_interval; |
288 | /* Stores the time when the last reseeding occurred */ |
289 | time_t reseed_time; |
290 | /* |
291 | * Specifies the maximum time interval (in seconds) between reseeds. |
292 | * This value is ignored if it is zero. |
293 | */ |
294 | time_t reseed_time_interval; |
295 | /* |
296 | * Counts the number of reseeds since instantiation. |
297 | * This value is ignored if it is zero. |
298 | * |
299 | * This counter is used only for seed propagation from the <master> DRBG |
300 | * to its two children, the <public> and <private> DRBG. This feature is |
301 | * very special and its sole purpose is to ensure that any randomness which |
302 | * is added by RAND_add() or RAND_seed() will have an immediate effect on |
303 | * the output of RAND_bytes() resp. RAND_priv_bytes(). |
304 | */ |
305 | TSAN_QUALIFIER unsigned int reseed_prop_counter; |
306 | unsigned int reseed_next_counter; |
307 | |
308 | size_t seedlen; |
309 | DRBG_STATUS state; |
310 | |
311 | /* Application data, mainly used in the KATs. */ |
312 | CRYPTO_EX_DATA ex_data; |
313 | |
314 | /* Implementation specific data */ |
315 | union { |
316 | RAND_DRBG_CTR ctr; |
317 | RAND_DRBG_HASH hash; |
318 | RAND_DRBG_HMAC hmac; |
319 | } data; |
320 | |
321 | /* Implementation specific methods */ |
322 | RAND_DRBG_METHOD *meth; |
323 | |
324 | /* Callback functions. See comments in rand_lib.c */ |
325 | RAND_DRBG_get_entropy_fn get_entropy; |
326 | RAND_DRBG_cleanup_entropy_fn cleanup_entropy; |
327 | RAND_DRBG_get_nonce_fn get_nonce; |
328 | RAND_DRBG_cleanup_nonce_fn cleanup_nonce; |
329 | }; |
330 | |
331 | /* The global RAND method, and the global buffer and DRBG instance. */ |
332 | extern RAND_METHOD rand_meth; |
333 | |
334 | /* DRBG helpers */ |
335 | int rand_drbg_restart(RAND_DRBG *drbg, |
336 | const unsigned char *buffer, size_t len, size_t entropy); |
337 | size_t rand_drbg_seedlen(RAND_DRBG *drbg); |
338 | /* locking api */ |
339 | int rand_drbg_lock(RAND_DRBG *drbg); |
340 | int rand_drbg_unlock(RAND_DRBG *drbg); |
341 | int rand_drbg_enable_locking(RAND_DRBG *drbg); |
342 | |
343 | |
344 | /* initializes the DRBG implementation */ |
345 | int drbg_ctr_init(RAND_DRBG *drbg); |
346 | int drbg_hash_init(RAND_DRBG *drbg); |
347 | int drbg_hmac_init(RAND_DRBG *drbg); |
348 | |
349 | /* |
350 | * Entropy call back for the FIPS 140-2 section 4.9.2 Conditional Tests. |
351 | * These need to be exposed for the unit tests. |
352 | */ |
353 | int rand_crngt_get_entropy_cb(OPENSSL_CTX *ctx, RAND_POOL *pool, |
354 | unsigned char *buf, unsigned char *md, |
355 | unsigned int *md_size); |
356 | extern int (*crngt_get_entropy)(OPENSSL_CTX *ctx, RAND_POOL *pool, |
357 | unsigned char *buf, unsigned char *md, |
358 | unsigned int *md_size); |
359 | |
360 | #endif |
361 | |