2 * Copyright 1995-2021 The OpenSSL Project Authors. All Rights Reserved.
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
12 #include "internal/cryptlib.h"
13 #include <openssl/opensslconf.h>
14 #include "crypto/rand.h"
15 #include <openssl/engine.h>
16 #include "internal/thread_once.h"
17 #include "crypto/rand_pool.h"
20 * Allocate memory and initialize a new random pool
22 RAND_POOL
*ossl_rand_pool_new(int entropy_requested
, int secure
,
23 size_t min_len
, size_t max_len
)
25 RAND_POOL
*pool
= OPENSSL_zalloc(sizeof(*pool
));
26 size_t min_alloc_size
= RAND_POOL_MIN_ALLOCATION(secure
);
31 pool
->min_len
= min_len
;
32 pool
->max_len
= (max_len
> RAND_POOL_MAX_LENGTH
) ?
33 RAND_POOL_MAX_LENGTH
: max_len
;
34 pool
->alloc_len
= min_len
< min_alloc_size
? min_alloc_size
: min_len
;
35 if (pool
->alloc_len
> pool
->max_len
)
36 pool
->alloc_len
= pool
->max_len
;
39 pool
->buffer
= OPENSSL_secure_zalloc(pool
->alloc_len
);
41 pool
->buffer
= OPENSSL_zalloc(pool
->alloc_len
);
43 if (pool
->buffer
== NULL
)
46 pool
->entropy_requested
= entropy_requested
;
47 pool
->secure
= secure
;
56 * Attach new random pool to the given buffer
58 * This function is intended to be used only for feeding random data
59 * provided by RAND_add() and RAND_seed() into the <master> DRBG.
61 RAND_POOL
*ossl_rand_pool_attach(const unsigned char *buffer
, size_t len
,
64 RAND_POOL
*pool
= OPENSSL_zalloc(sizeof(*pool
));
70 * The const needs to be cast away, but attached buffers will not be
71 * modified (in contrary to allocated buffers which are zeroed and
74 pool
->buffer
= (unsigned char *) buffer
;
79 pool
->min_len
= pool
->max_len
= pool
->alloc_len
= pool
->len
;
80 pool
->entropy
= entropy
;
86 * Free |pool|, securely erasing its buffer.
88 void ossl_rand_pool_free(RAND_POOL
*pool
)
94 * Although it would be advisable from a cryptographical viewpoint,
95 * we are not allowed to clear attached buffers, since they are passed
96 * to ossl_rand_pool_attach() as `const unsigned char*`.
97 * (see corresponding comment in ossl_rand_pool_attach()).
99 if (!pool
->attached
) {
101 OPENSSL_secure_clear_free(pool
->buffer
, pool
->alloc_len
);
103 OPENSSL_clear_free(pool
->buffer
, pool
->alloc_len
);
110 * Return the |pool|'s buffer to the caller (readonly).
112 const unsigned char *ossl_rand_pool_buffer(RAND_POOL
*pool
)
118 * Return the |pool|'s entropy to the caller.
120 size_t ossl_rand_pool_entropy(RAND_POOL
*pool
)
122 return pool
->entropy
;
126 * Return the |pool|'s buffer length to the caller.
128 size_t ossl_rand_pool_length(RAND_POOL
*pool
)
134 * Detach the |pool| buffer and return it to the caller.
135 * It's the responsibility of the caller to free the buffer
136 * using OPENSSL_secure_clear_free() or to re-attach it
137 * again to the pool using ossl_rand_pool_reattach().
139 unsigned char *ossl_rand_pool_detach(RAND_POOL
*pool
)
141 unsigned char *ret
= pool
->buffer
;
148 * Re-attach the |pool| buffer. It is only allowed to pass
149 * the |buffer| which was previously detached from the same pool.
151 void ossl_rand_pool_reattach(RAND_POOL
*pool
, unsigned char *buffer
)
153 pool
->buffer
= buffer
;
154 OPENSSL_cleanse(pool
->buffer
, pool
->len
);
159 * If |entropy_factor| bits contain 1 bit of entropy, how many bytes does one
160 * need to obtain at least |bits| bits of entropy?
162 #define ENTROPY_TO_BYTES(bits, entropy_factor) \
163 (((bits) * (entropy_factor) + 7) / 8)
167 * Checks whether the |pool|'s entropy is available to the caller.
168 * This is the case when entropy count and buffer length are high enough.
171 * |entropy| if the entropy count and buffer size is large enough
174 size_t ossl_rand_pool_entropy_available(RAND_POOL
*pool
)
176 if (pool
->entropy
< pool
->entropy_requested
)
179 if (pool
->len
< pool
->min_len
)
182 return pool
->entropy
;
186 * Returns the (remaining) amount of entropy needed to fill
190 size_t ossl_rand_pool_entropy_needed(RAND_POOL
*pool
)
192 if (pool
->entropy
< pool
->entropy_requested
)
193 return pool
->entropy_requested
- pool
->entropy
;
198 /* Increase the allocation size -- not usable for an attached pool */
199 static int rand_pool_grow(RAND_POOL
*pool
, size_t len
)
201 if (len
> pool
->alloc_len
- pool
->len
) {
203 const size_t limit
= pool
->max_len
/ 2;
204 size_t newlen
= pool
->alloc_len
;
206 if (pool
->attached
|| len
> pool
->max_len
- pool
->len
) {
207 ERR_raise(ERR_LIB_RAND
, ERR_R_INTERNAL_ERROR
);
212 newlen
= newlen
< limit
? newlen
* 2 : pool
->max_len
;
213 while (len
> newlen
- pool
->len
);
216 p
= OPENSSL_secure_zalloc(newlen
);
218 p
= OPENSSL_zalloc(newlen
);
221 memcpy(p
, pool
->buffer
, pool
->len
);
223 OPENSSL_secure_clear_free(pool
->buffer
, pool
->alloc_len
);
225 OPENSSL_clear_free(pool
->buffer
, pool
->alloc_len
);
227 pool
->alloc_len
= newlen
;
233 * Returns the number of bytes needed to fill the pool, assuming
234 * the input has 1 / |entropy_factor| entropy bits per data bit.
235 * In case of an error, 0 is returned.
238 size_t ossl_rand_pool_bytes_needed(RAND_POOL
*pool
, unsigned int entropy_factor
)
241 size_t entropy_needed
= ossl_rand_pool_entropy_needed(pool
);
243 if (entropy_factor
< 1) {
244 ERR_raise(ERR_LIB_RAND
, RAND_R_ARGUMENT_OUT_OF_RANGE
);
248 bytes_needed
= ENTROPY_TO_BYTES(entropy_needed
, entropy_factor
);
250 if (bytes_needed
> pool
->max_len
- pool
->len
) {
251 /* not enough space left */
252 ERR_raise(ERR_LIB_RAND
, RAND_R_RANDOM_POOL_OVERFLOW
);
256 if (pool
->len
< pool
->min_len
&&
257 bytes_needed
< pool
->min_len
- pool
->len
)
258 /* to meet the min_len requirement */
259 bytes_needed
= pool
->min_len
- pool
->len
;
262 * Make sure the buffer is large enough for the requested amount
263 * of data. This guarantees that existing code patterns where
264 * ossl_rand_pool_add_begin, ossl_rand_pool_add_end or ossl_rand_pool_add
265 * are used to collect entropy data without any error handling
266 * whatsoever, continue to be valid.
267 * Furthermore if the allocation here fails once, make sure that
268 * we don't fall back to a less secure or even blocking random source,
269 * as that could happen by the existing code patterns.
270 * This is not a concern for additional data, therefore that
271 * is not needed if rand_pool_grow fails in other places.
273 if (!rand_pool_grow(pool
, bytes_needed
)) {
274 /* persistent error for this pool */
275 pool
->max_len
= pool
->len
= 0;
282 /* Returns the remaining number of bytes available */
283 size_t ossl_rand_pool_bytes_remaining(RAND_POOL
*pool
)
285 return pool
->max_len
- pool
->len
;
289 * Add random bytes to the random pool.
291 * It is expected that the |buffer| contains |len| bytes of
292 * random input which contains at least |entropy| bits of
295 * Returns 1 if the added amount is adequate, otherwise 0
297 int ossl_rand_pool_add(RAND_POOL
*pool
,
298 const unsigned char *buffer
, size_t len
, size_t entropy
)
300 if (len
> pool
->max_len
- pool
->len
) {
301 ERR_raise(ERR_LIB_RAND
, RAND_R_ENTROPY_INPUT_TOO_LONG
);
305 if (pool
->buffer
== NULL
) {
306 ERR_raise(ERR_LIB_RAND
, ERR_R_INTERNAL_ERROR
);
312 * This is to protect us from accidentally passing the buffer
313 * returned from ossl_rand_pool_add_begin.
314 * The check for alloc_len makes sure we do not compare the
315 * address of the end of the allocated memory to something
316 * different, since that comparison would have an
317 * indeterminate result.
319 if (pool
->alloc_len
> pool
->len
&& pool
->buffer
+ pool
->len
== buffer
) {
320 ERR_raise(ERR_LIB_RAND
, ERR_R_INTERNAL_ERROR
);
324 * We have that only for cases when a pool is used to collect
326 * For entropy data, as long as the allocation request stays within
327 * the limits given by ossl_rand_pool_bytes_needed this rand_pool_grow
328 * below is guaranteed to succeed, thus no allocation happens.
330 if (!rand_pool_grow(pool
, len
))
332 memcpy(pool
->buffer
+ pool
->len
, buffer
, len
);
334 pool
->entropy
+= entropy
;
341 * Start to add random bytes to the random pool in-place.
343 * Reserves the next |len| bytes for adding random bytes in-place
344 * and returns a pointer to the buffer.
345 * The caller is allowed to copy up to |len| bytes into the buffer.
346 * If |len| == 0 this is considered a no-op and a NULL pointer
347 * is returned without producing an error message.
349 * After updating the buffer, ossl_rand_pool_add_end() needs to be called
350 * to finish the update operation (see next comment).
352 unsigned char *ossl_rand_pool_add_begin(RAND_POOL
*pool
, size_t len
)
357 if (len
> pool
->max_len
- pool
->len
) {
358 ERR_raise(ERR_LIB_RAND
, RAND_R_RANDOM_POOL_OVERFLOW
);
362 if (pool
->buffer
== NULL
) {
363 ERR_raise(ERR_LIB_RAND
, ERR_R_INTERNAL_ERROR
);
368 * As long as the allocation request stays within the limits given
369 * by ossl_rand_pool_bytes_needed this rand_pool_grow below is guaranteed
370 * to succeed, thus no allocation happens.
371 * We have that only for cases when a pool is used to collect
372 * additional data. Then the buffer might need to grow here,
373 * and of course the caller is responsible to check the return
374 * value of this function.
376 if (!rand_pool_grow(pool
, len
))
379 return pool
->buffer
+ pool
->len
;
383 * Finish to add random bytes to the random pool in-place.
385 * Finishes an in-place update of the random pool started by
386 * ossl_rand_pool_add_begin() (see previous comment).
387 * It is expected that |len| bytes of random input have been added
388 * to the buffer which contain at least |entropy| bits of randomness.
389 * It is allowed to add less bytes than originally reserved.
391 int ossl_rand_pool_add_end(RAND_POOL
*pool
, size_t len
, size_t entropy
)
393 if (len
> pool
->alloc_len
- pool
->len
) {
394 ERR_raise(ERR_LIB_RAND
, RAND_R_RANDOM_POOL_OVERFLOW
);
400 pool
->entropy
+= entropy
;