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);
29 ERR_raise(ERR_LIB_RAND, ERR_R_MALLOC_FAILURE);
33 pool->min_len = min_len;
34 pool->max_len = (max_len > RAND_POOL_MAX_LENGTH) ?
35 RAND_POOL_MAX_LENGTH : max_len;
36 pool->alloc_len = min_len < min_alloc_size ? min_alloc_size : min_len;
37 if (pool->alloc_len > pool->max_len)
38 pool->alloc_len = pool->max_len;
41 pool->buffer = OPENSSL_secure_zalloc(pool->alloc_len);
43 pool->buffer = OPENSSL_zalloc(pool->alloc_len);
45 if (pool->buffer == NULL) {
46 ERR_raise(ERR_LIB_RAND, ERR_R_MALLOC_FAILURE);
50 pool->entropy_requested = entropy_requested;
51 pool->secure = secure;
60 * Attach new random pool to the given buffer
62 * This function is intended to be used only for feeding random data
63 * provided by RAND_add() and RAND_seed() into the <master> DRBG.
65 RAND_POOL *ossl_rand_pool_attach(const unsigned char *buffer, size_t len,
68 RAND_POOL *pool = OPENSSL_zalloc(sizeof(*pool));
71 ERR_raise(ERR_LIB_RAND, ERR_R_MALLOC_FAILURE);
76 * The const needs to be cast away, but attached buffers will not be
77 * modified (in contrary to allocated buffers which are zeroed and
80 pool->buffer = (unsigned char *) buffer;
85 pool->min_len = pool->max_len = pool->alloc_len = pool->len;
86 pool->entropy = entropy;
92 * Free |pool|, securely erasing its buffer.
94 void ossl_rand_pool_free(RAND_POOL *pool)
100 * Although it would be advisable from a cryptographical viewpoint,
101 * we are not allowed to clear attached buffers, since they are passed
102 * to ossl_rand_pool_attach() as `const unsigned char*`.
103 * (see corresponding comment in ossl_rand_pool_attach()).
105 if (!pool->attached) {
107 OPENSSL_secure_clear_free(pool->buffer, pool->alloc_len);
109 OPENSSL_clear_free(pool->buffer, pool->alloc_len);
116 * Return the |pool|'s buffer to the caller (readonly).
118 const unsigned char *ossl_rand_pool_buffer(RAND_POOL *pool)
124 * Return the |pool|'s entropy to the caller.
126 size_t ossl_rand_pool_entropy(RAND_POOL *pool)
128 return pool->entropy;
132 * Return the |pool|'s buffer length to the caller.
134 size_t ossl_rand_pool_length(RAND_POOL *pool)
140 * Detach the |pool| buffer and return it to the caller.
141 * It's the responsibility of the caller to free the buffer
142 * using OPENSSL_secure_clear_free() or to re-attach it
143 * again to the pool using ossl_rand_pool_reattach().
145 unsigned char *ossl_rand_pool_detach(RAND_POOL *pool)
147 unsigned char *ret = pool->buffer;
154 * Re-attach the |pool| buffer. It is only allowed to pass
155 * the |buffer| which was previously detached from the same pool.
157 void ossl_rand_pool_reattach(RAND_POOL *pool, unsigned char *buffer)
159 pool->buffer = buffer;
160 OPENSSL_cleanse(pool->buffer, pool->len);
165 * If |entropy_factor| bits contain 1 bit of entropy, how many bytes does one
166 * need to obtain at least |bits| bits of entropy?
168 #define ENTROPY_TO_BYTES(bits, entropy_factor) \
169 (((bits) * (entropy_factor) + 7) / 8)
173 * Checks whether the |pool|'s entropy is available to the caller.
174 * This is the case when entropy count and buffer length are high enough.
177 * |entropy| if the entropy count and buffer size is large enough
180 size_t ossl_rand_pool_entropy_available(RAND_POOL *pool)
182 if (pool->entropy < pool->entropy_requested)
185 if (pool->len < pool->min_len)
188 return pool->entropy;
192 * Returns the (remaining) amount of entropy needed to fill
196 size_t ossl_rand_pool_entropy_needed(RAND_POOL *pool)
198 if (pool->entropy < pool->entropy_requested)
199 return pool->entropy_requested - pool->entropy;
204 /* Increase the allocation size -- not usable for an attached pool */
205 static int rand_pool_grow(RAND_POOL *pool, size_t len)
207 if (len > pool->alloc_len - pool->len) {
209 const size_t limit = pool->max_len / 2;
210 size_t newlen = pool->alloc_len;
212 if (pool->attached || len > pool->max_len - pool->len) {
213 ERR_raise(ERR_LIB_RAND, ERR_R_INTERNAL_ERROR);
218 newlen = newlen < limit ? newlen * 2 : pool->max_len;
219 while (len > newlen - pool->len);
222 p = OPENSSL_secure_zalloc(newlen);
224 p = OPENSSL_zalloc(newlen);
226 ERR_raise(ERR_LIB_RAND, ERR_R_MALLOC_FAILURE);
229 memcpy(p, pool->buffer, pool->len);
231 OPENSSL_secure_clear_free(pool->buffer, pool->alloc_len);
233 OPENSSL_clear_free(pool->buffer, pool->alloc_len);
235 pool->alloc_len = newlen;
241 * Returns the number of bytes needed to fill the pool, assuming
242 * the input has 1 / |entropy_factor| entropy bits per data bit.
243 * In case of an error, 0 is returned.
246 size_t ossl_rand_pool_bytes_needed(RAND_POOL *pool, unsigned int entropy_factor)
249 size_t entropy_needed = ossl_rand_pool_entropy_needed(pool);
251 if (entropy_factor < 1) {
252 ERR_raise(ERR_LIB_RAND, RAND_R_ARGUMENT_OUT_OF_RANGE);
256 bytes_needed = ENTROPY_TO_BYTES(entropy_needed, entropy_factor);
258 if (bytes_needed > pool->max_len - pool->len) {
259 /* not enough space left */
260 ERR_raise(ERR_LIB_RAND, RAND_R_RANDOM_POOL_OVERFLOW);
264 if (pool->len < pool->min_len &&
265 bytes_needed < pool->min_len - pool->len)
266 /* to meet the min_len requirement */
267 bytes_needed = pool->min_len - pool->len;
270 * Make sure the buffer is large enough for the requested amount
271 * of data. This guarantees that existing code patterns where
272 * ossl_rand_pool_add_begin, ossl_rand_pool_add_end or ossl_rand_pool_add
273 * are used to collect entropy data without any error handling
274 * whatsoever, continue to be valid.
275 * Furthermore if the allocation here fails once, make sure that
276 * we don't fall back to a less secure or even blocking random source,
277 * as that could happen by the existing code patterns.
278 * This is not a concern for additional data, therefore that
279 * is not needed if rand_pool_grow fails in other places.
281 if (!rand_pool_grow(pool, bytes_needed)) {
282 /* persistent error for this pool */
283 pool->max_len = pool->len = 0;
290 /* Returns the remaining number of bytes available */
291 size_t ossl_rand_pool_bytes_remaining(RAND_POOL *pool)
293 return pool->max_len - pool->len;
297 * Add random bytes to the random pool.
299 * It is expected that the |buffer| contains |len| bytes of
300 * random input which contains at least |entropy| bits of
303 * Returns 1 if the added amount is adequate, otherwise 0
305 int ossl_rand_pool_add(RAND_POOL *pool,
306 const unsigned char *buffer, size_t len, size_t entropy)
308 if (len > pool->max_len - pool->len) {
309 ERR_raise(ERR_LIB_RAND, RAND_R_ENTROPY_INPUT_TOO_LONG);
313 if (pool->buffer == NULL) {
314 ERR_raise(ERR_LIB_RAND, ERR_R_INTERNAL_ERROR);
320 * This is to protect us from accidentally passing the buffer
321 * returned from ossl_rand_pool_add_begin.
322 * The check for alloc_len makes sure we do not compare the
323 * address of the end of the allocated memory to something
324 * different, since that comparison would have an
325 * indeterminate result.
327 if (pool->alloc_len > pool->len && pool->buffer + pool->len == buffer) {
328 ERR_raise(ERR_LIB_RAND, ERR_R_INTERNAL_ERROR);
332 * We have that only for cases when a pool is used to collect
334 * For entropy data, as long as the allocation request stays within
335 * the limits given by ossl_rand_pool_bytes_needed this rand_pool_grow
336 * below is guaranteed to succeed, thus no allocation happens.
338 if (!rand_pool_grow(pool, len))
340 memcpy(pool->buffer + pool->len, buffer, len);
342 pool->entropy += entropy;
349 * Start to add random bytes to the random pool in-place.
351 * Reserves the next |len| bytes for adding random bytes in-place
352 * and returns a pointer to the buffer.
353 * The caller is allowed to copy up to |len| bytes into the buffer.
354 * If |len| == 0 this is considered a no-op and a NULL pointer
355 * is returned without producing an error message.
357 * After updating the buffer, ossl_rand_pool_add_end() needs to be called
358 * to finish the update operation (see next comment).
360 unsigned char *ossl_rand_pool_add_begin(RAND_POOL *pool, size_t len)
365 if (len > pool->max_len - pool->len) {
366 ERR_raise(ERR_LIB_RAND, RAND_R_RANDOM_POOL_OVERFLOW);
370 if (pool->buffer == NULL) {
371 ERR_raise(ERR_LIB_RAND, ERR_R_INTERNAL_ERROR);
376 * As long as the allocation request stays within the limits given
377 * by ossl_rand_pool_bytes_needed this rand_pool_grow below is guaranteed
378 * to succeed, thus no allocation happens.
379 * We have that only for cases when a pool is used to collect
380 * additional data. Then the buffer might need to grow here,
381 * and of course the caller is responsible to check the return
382 * value of this function.
384 if (!rand_pool_grow(pool, len))
387 return pool->buffer + pool->len;
391 * Finish to add random bytes to the random pool in-place.
393 * Finishes an in-place update of the random pool started by
394 * ossl_rand_pool_add_begin() (see previous comment).
395 * It is expected that |len| bytes of random input have been added
396 * to the buffer which contain at least |entropy| bits of randomness.
397 * It is allowed to add less bytes than originally reserved.
399 int ossl_rand_pool_add_end(RAND_POOL *pool, size_t len, size_t entropy)
401 if (len > pool->alloc_len - pool->len) {
402 ERR_raise(ERR_LIB_RAND, RAND_R_RANDOM_POOL_OVERFLOW);
408 pool->entropy += entropy;