crypto/rand/rand_pool.c

   1 /*
   2  * Copyright 1995-2021 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 #include <stdio.h>
  11 #include <time.h>
  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"
  18
  19 /*
  20  * Allocate memory and initialize a new random pool
  21  */
  22 RAND_POOL *ossl_rand_pool_new(int entropy_requested, int secure,
  23                               size_t min_len, size_t max_len)
  24 {
  25     RAND_POOL *pool = OPENSSL_zalloc(sizeof(*pool));
  26     size_t min_alloc_size = RAND_POOL_MIN_ALLOCATION(secure);
  27
  28     if (pool == NULL) {
  29         ERR_raise(ERR_LIB_RAND, ERR_R_MALLOC_FAILURE);
  30         return NULL;
  31     }
  32
  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;
  39
  40     if (secure)
  41         pool->buffer = OPENSSL_secure_zalloc(pool->alloc_len);
  42     else
  43         pool->buffer = OPENSSL_zalloc(pool->alloc_len);
  44
  45     if (pool->buffer == NULL) {
  46         ERR_raise(ERR_LIB_RAND, ERR_R_MALLOC_FAILURE);
  47         goto err;
  48     }
  49
  50     pool->entropy_requested = entropy_requested;
  51     pool->secure = secure;
  52     return pool;
  53
  54 err:
  55     OPENSSL_free(pool);
  56     return NULL;
  57 }
  58
  59 /*
  60  * Attach new random pool to the given buffer
  61  *
  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.
  64  */
  65 RAND_POOL *ossl_rand_pool_attach(const unsigned char *buffer, size_t len,
  66                                  size_t entropy)
  67 {
  68     RAND_POOL *pool = OPENSSL_zalloc(sizeof(*pool));
  69
  70     if (pool == NULL) {
  71         ERR_raise(ERR_LIB_RAND, ERR_R_MALLOC_FAILURE);
  72         return NULL;
  73     }
  74
  75     /*
  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
  78      * freed in the end).
  79      */
  80     pool->buffer = (unsigned char *) buffer;
  81     pool->len = len;
  82
  83     pool->attached = 1;
  84
  85     pool->min_len = pool->max_len = pool->alloc_len = pool->len;
  86     pool->entropy = entropy;
  87
  88     return pool;
  89 }
  90
  91 /*
  92  * Free |pool|, securely erasing its buffer.
  93  */
  94 void ossl_rand_pool_free(RAND_POOL *pool)
  95 {
  96     if (pool == NULL)
  97         return;
  98
  99     /*
 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()).
 104      */
 105     if (!pool->attached) {
 106         if (pool->secure)
 107             OPENSSL_secure_clear_free(pool->buffer, pool->alloc_len);
 108         else
 109             OPENSSL_clear_free(pool->buffer, pool->alloc_len);
 110     }
 111
 112     OPENSSL_free(pool);
 113 }
 114
 115 /*
 116  * Return the |pool|'s buffer to the caller (readonly).
 117  */
 118 const unsigned char *ossl_rand_pool_buffer(RAND_POOL *pool)
 119 {
 120     return pool->buffer;
 121 }
 122
 123 /*
 124  * Return the |pool|'s entropy to the caller.
 125  */
 126 size_t ossl_rand_pool_entropy(RAND_POOL *pool)
 127 {
 128     return pool->entropy;
 129 }
 130
 131 /*
 132  * Return the |pool|'s buffer length to the caller.
 133  */
 134 size_t ossl_rand_pool_length(RAND_POOL *pool)
 135 {
 136     return pool->len;
 137 }
 138
 139 /*
 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().
 144  */
 145 unsigned char *ossl_rand_pool_detach(RAND_POOL *pool)
 146 {
 147     unsigned char *ret = pool->buffer;
 148     pool->buffer = NULL;
 149     pool->entropy = 0;
 150     return ret;
 151 }
 152
 153 /*
 154  * Re-attach the |pool| buffer. It is only allowed to pass
 155  * the |buffer| which was previously detached from the same pool.
 156  */
 157 void ossl_rand_pool_reattach(RAND_POOL *pool, unsigned char *buffer)
 158 {
 159     pool->buffer = buffer;
 160     OPENSSL_cleanse(pool->buffer, pool->len);
 161     pool->len = 0;
 162 }
 163
 164 /*
 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?
 167  */
 168 #define ENTROPY_TO_BYTES(bits, entropy_factor) \
 169     (((bits) * (entropy_factor) + 7) / 8)
 170
 171
 172 /*
 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.
 175  * Returns
 176  *
 177  *  |entropy|  if the entropy count and buffer size is large enough
 178  *      0      otherwise
 179  */
 180 size_t ossl_rand_pool_entropy_available(RAND_POOL *pool)
 181 {
 182     if (pool->entropy < pool->entropy_requested)
 183         return 0;
 184
 185     if (pool->len < pool->min_len)
 186         return 0;
 187
 188     return pool->entropy;
 189 }
 190
 191 /*
 192  * Returns the (remaining) amount of entropy needed to fill
 193  * the random pool.
 194  */
 195
 196 size_t ossl_rand_pool_entropy_needed(RAND_POOL *pool)
 197 {
 198     if (pool->entropy < pool->entropy_requested)
 199         return pool->entropy_requested - pool->entropy;
 200
 201     return 0;
 202 }
 203
 204 /* Increase the allocation size -- not usable for an attached pool */
 205 static int rand_pool_grow(RAND_POOL *pool, size_t len)
 206 {
 207     if (len > pool->alloc_len - pool->len) {
 208         unsigned char *p;
 209         const size_t limit = pool->max_len / 2;
 210         size_t newlen = pool->alloc_len;
 211
 212         if (pool->attached || len > pool->max_len - pool->len) {
 213             ERR_raise(ERR_LIB_RAND, ERR_R_INTERNAL_ERROR);
 214             return 0;
 215         }
 216
 217         do
 218             newlen = newlen < limit ? newlen * 2 : pool->max_len;
 219         while (len > newlen - pool->len);
 220
 221         if (pool->secure)
 222             p = OPENSSL_secure_zalloc(newlen);
 223         else
 224             p = OPENSSL_zalloc(newlen);
 225         if (p == NULL) {
 226             ERR_raise(ERR_LIB_RAND, ERR_R_MALLOC_FAILURE);
 227             return 0;
 228         }
 229         memcpy(p, pool->buffer, pool->len);
 230         if (pool->secure)
 231             OPENSSL_secure_clear_free(pool->buffer, pool->alloc_len);
 232         else
 233             OPENSSL_clear_free(pool->buffer, pool->alloc_len);
 234         pool->buffer = p;
 235         pool->alloc_len = newlen;
 236     }
 237     return 1;
 238 }
 239
 240 /*
 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.
 244  */
 245
 246 size_t ossl_rand_pool_bytes_needed(RAND_POOL *pool, unsigned int entropy_factor)
 247 {
 248     size_t bytes_needed;
 249     size_t entropy_needed = ossl_rand_pool_entropy_needed(pool);
 250
 251     if (entropy_factor < 1) {
 252         ERR_raise(ERR_LIB_RAND, RAND_R_ARGUMENT_OUT_OF_RANGE);
 253         return 0;
 254     }
 255
 256     bytes_needed = ENTROPY_TO_BYTES(entropy_needed, entropy_factor);
 257
 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);
 261         return 0;
 262     }
 263
 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;
 268
 269     /*
 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.
 280      */
 281     if (!rand_pool_grow(pool, bytes_needed)) {
 282         /* persistent error for this pool */
 283         pool->max_len = pool->len = 0;
 284         return 0;
 285     }
 286
 287     return bytes_needed;
 288 }
 289
 290 /* Returns the remaining number of bytes available */
 291 size_t ossl_rand_pool_bytes_remaining(RAND_POOL *pool)
 292 {
 293     return pool->max_len - pool->len;
 294 }
 295
 296 /*
 297  * Add random bytes to the random pool.
 298  *
 299  * It is expected that the |buffer| contains |len| bytes of
 300  * random input which contains at least |entropy| bits of
 301  * randomness.
 302  *
 303  * Returns 1 if the added amount is adequate, otherwise 0
 304  */
 305 int ossl_rand_pool_add(RAND_POOL *pool,
 306                   const unsigned char *buffer, size_t len, size_t entropy)
 307 {
 308     if (len > pool->max_len - pool->len) {
 309         ERR_raise(ERR_LIB_RAND, RAND_R_ENTROPY_INPUT_TOO_LONG);
 310         return 0;
 311     }
 312
 313     if (pool->buffer == NULL) {
 314         ERR_raise(ERR_LIB_RAND, ERR_R_INTERNAL_ERROR);
 315         return 0;
 316     }
 317
 318     if (len > 0) {
 319         /*
 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.
 326          */
 327         if (pool->alloc_len > pool->len && pool->buffer + pool->len == buffer) {
 328             ERR_raise(ERR_LIB_RAND, ERR_R_INTERNAL_ERROR);
 329             return 0;
 330         }
 331         /*
 332          * We have that only for cases when a pool is used to collect
 333          * additional data.
 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.
 337          */
 338         if (!rand_pool_grow(pool, len))
 339             return 0;
 340         memcpy(pool->buffer + pool->len, buffer, len);
 341         pool->len += len;
 342         pool->entropy += entropy;
 343     }
 344
 345     return 1;
 346 }
 347
 348 /*
 349  * Start to add random bytes to the random pool in-place.
 350  *
 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.
 356  *
 357  * After updating the buffer, ossl_rand_pool_add_end() needs to be called
 358  * to finish the update operation (see next comment).
 359  */
 360 unsigned char *ossl_rand_pool_add_begin(RAND_POOL *pool, size_t len)
 361 {
 362     if (len == 0)
 363         return NULL;
 364
 365     if (len > pool->max_len - pool->len) {
 366         ERR_raise(ERR_LIB_RAND, RAND_R_RANDOM_POOL_OVERFLOW);
 367         return NULL;
 368     }
 369
 370     if (pool->buffer == NULL) {
 371         ERR_raise(ERR_LIB_RAND, ERR_R_INTERNAL_ERROR);
 372         return NULL;
 373     }
 374
 375     /*
 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.
 383      */
 384     if (!rand_pool_grow(pool, len))
 385         return NULL;
 386
 387     return pool->buffer + pool->len;
 388 }
 389
 390 /*
 391  * Finish to add random bytes to the random pool in-place.
 392  *
 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.
 398  */
 399 int ossl_rand_pool_add_end(RAND_POOL *pool, size_t len, size_t entropy)
 400 {
 401     if (len > pool->alloc_len - pool->len) {
 402         ERR_raise(ERR_LIB_RAND, RAND_R_RANDOM_POOL_OVERFLOW);
 403         return 0;
 404     }
 405
 406     if (len > 0) {
 407         pool->len += len;
 408         pool->entropy += entropy;
 409     }
 410
 411     return 1;
 412 }