include/crypto/rand.h

   1 /*
   2  * Copyright 2016-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 /*
  11  * Licensed under the Apache License 2.0 (the "License");
  12  * you may not use this file except in compliance with the License.
  13  * You may obtain a copy of the License at
  14  * https://www.openssl.org/source/license.html
  15  * or in the file LICENSE in the source distribution.
  16  */
  17
  18 #ifndef OSSL_CRYPTO_RAND_H
  19 # define OSSL_CRYPTO_RAND_H
  20
  21 # include <openssl/rand.h>
  22
  23 /* forward declaration */
  24 typedef struct rand_pool_st RAND_POOL;
  25
  26 /*
  27  * Defines related to seed sources
  28  */
  29 #ifndef DEVRANDOM
  30 /*
  31  * set this to a comma-separated list of 'random' device files to try out. By
  32  * default, we will try to read at least one of these files
  33  */
  34 # define DEVRANDOM "/dev/urandom", "/dev/random", "/dev/hwrng", "/dev/srandom"
  35 # if defined(__linux) && !defined(__ANDROID__)
  36 #  ifndef DEVRANDOM_WAIT
  37 #   define DEVRANDOM_WAIT   "/dev/random"
  38 #  endif
  39 /*
  40  * Linux kernels 4.8 and later changes how their random device works and there
  41  * is no reliable way to tell that /dev/urandom has been seeded -- getentropy(2)
  42  * should be used instead.
  43  */
  44 #  ifndef DEVRANDOM_SAFE_KERNEL
  45 #   define DEVRANDOM_SAFE_KERNEL        4, 8
  46 #  endif
  47 /*
  48  * Some operating systems do not permit select(2) on their random devices,
  49  * defining this to zero will force the use of read(2) to extract one byte
  50  * from /dev/random.
  51  */
  52 #  ifndef DEVRANDM_WAIT_USE_SELECT
  53 #   define DEVRANDM_WAIT_USE_SELECT     1
  54 #  endif
  55 /*
  56  * Define the shared memory identifier used to indicate if the operating
  57  * system has properly seeded the DEVRANDOM source.
  58  */
  59 #  ifndef OPENSSL_RAND_SEED_DEVRANDOM_SHM_ID
  60 #   define OPENSSL_RAND_SEED_DEVRANDOM_SHM_ID 114
  61 #  endif
  62
  63 # endif
  64 #endif
  65
  66 #if !defined(OPENSSL_NO_EGD) && !defined(DEVRANDOM_EGD)
  67 /*
  68  * set this to a comma-separated list of 'egd' sockets to try out. These
  69  * sockets will be tried in the order listed in case accessing the device
  70  * files listed in DEVRANDOM did not return enough randomness.
  71  */
  72 # define DEVRANDOM_EGD "/var/run/egd-pool", "/dev/egd-pool", "/etc/egd-pool", "/etc/entropy"
  73 #endif
  74
  75 void rand_cleanup_int(void);
  76
  77 /* Hardware-based seeding functions. */
  78 size_t rand_acquire_entropy_from_tsc(RAND_POOL *pool);
  79 size_t rand_acquire_entropy_from_cpu(RAND_POOL *pool);
  80
  81 /* DRBG entropy callbacks. */
  82 size_t rand_drbg_get_entropy(RAND_DRBG *drbg,
  83                              unsigned char **pout,
  84                              int entropy, size_t min_len, size_t max_len,
  85                              int prediction_resistance);
  86 void rand_drbg_cleanup_entropy(RAND_DRBG *drbg,
  87                                unsigned char *out, size_t outlen);
  88 size_t rand_drbg_get_nonce(RAND_DRBG *drbg,
  89                            unsigned char **pout,
  90                            int entropy, size_t min_len, size_t max_len);
  91 void rand_drbg_cleanup_nonce(RAND_DRBG *drbg,
  92                              unsigned char *out, size_t outlen);
  93
  94 size_t rand_drbg_get_additional_data(RAND_POOL *pool, unsigned char **pout);
  95
  96 void rand_drbg_cleanup_additional_data(RAND_POOL *pool, unsigned char *out);
  97
  98 /* CRNG test entropy filter callbacks. */
  99 size_t rand_crngt_get_entropy(RAND_DRBG *drbg,
 100                               unsigned char **pout,
 101                               int entropy, size_t min_len, size_t max_len,
 102                               int prediction_resistance);
 103 void rand_crngt_cleanup_entropy(RAND_DRBG *drbg,
 104                                 unsigned char *out, size_t outlen);
 105
 106 /*
 107  * RAND_POOL functions
 108  */
 109 RAND_POOL *rand_pool_new(int entropy_requested, int secure,
 110                          size_t min_len, size_t max_len);
 111 RAND_POOL *rand_pool_attach(const unsigned char *buffer, size_t len,
 112                             size_t entropy);
 113 void rand_pool_free(RAND_POOL *pool);
 114
 115 const unsigned char *rand_pool_buffer(RAND_POOL *pool);
 116 unsigned char *rand_pool_detach(RAND_POOL *pool);
 117 void rand_pool_reattach(RAND_POOL *pool, unsigned char *buffer);
 118
 119 size_t rand_pool_entropy(RAND_POOL *pool);
 120 size_t rand_pool_length(RAND_POOL *pool);
 121
 122 size_t rand_pool_entropy_available(RAND_POOL *pool);
 123 size_t rand_pool_entropy_needed(RAND_POOL *pool);
 124 /* |entropy_factor| expresses how many bits of data contain 1 bit of entropy */
 125 size_t rand_pool_bytes_needed(RAND_POOL *pool, unsigned int entropy_factor);
 126 size_t rand_pool_bytes_remaining(RAND_POOL *pool);
 127
 128 int rand_pool_add(RAND_POOL *pool,
 129                   const unsigned char *buffer, size_t len, size_t entropy);
 130 unsigned char *rand_pool_add_begin(RAND_POOL *pool, size_t len);
 131 int rand_pool_add_end(RAND_POOL *pool, size_t len, size_t entropy);
 132
 133
 134 /*
 135  * Add random bytes to the pool to acquire requested amount of entropy
 136  *
 137  * This function is platform specific and tries to acquire the requested
 138  * amount of entropy by polling platform specific entropy sources.
 139  *
 140  * If the function succeeds in acquiring at least |entropy_requested| bits
 141  * of entropy, the total entropy count is returned. If it fails, it returns
 142  * an entropy count of 0.
 143  */
 144 size_t rand_pool_acquire_entropy(RAND_POOL *pool);
 145
 146 /*
 147  * Add some application specific nonce data
 148  *
 149  * This function is platform specific and adds some application specific
 150  * data to the nonce used for instantiating the drbg.
 151  *
 152  * This data currently consists of the process and thread id, and a high
 153  * resolution timestamp. The data does not include an atomic counter,
 154  * because that is added by the calling function rand_drbg_get_nonce().
 155  *
 156  * Returns 1 on success and 0 on failure.
 157  */
 158 int rand_pool_add_nonce_data(RAND_POOL *pool);
 159
 160
 161 /*
 162  * Add some platform specific additional data
 163  *
 164  * This function is platform specific and adds some random noise to the
 165  * additional data used for generating random bytes and for reseeding
 166  * the drbg.
 167  *
 168  * Returns 1 on success and 0 on failure.
 169  */
 170 int rand_pool_add_additional_data(RAND_POOL *pool);
 171
 172 /*
 173  * Initialise the random pool reseeding sources.
 174  *
 175  * Returns 1 on success and 0 on failure.
 176  */
 177 int rand_pool_init(void);
 178
 179 /*
 180  * Finalise the random pool reseeding sources.
 181  */
 182 void rand_pool_cleanup(void);
 183
 184 /*
 185  * Control the random pool use of open file descriptors.
 186  */
 187 void rand_pool_keep_random_devices_open(int keep);
 188
 189 /* Equivalent of RAND_priv_bytes() but additionally taking an OPENSSL_CTX */
 190 int rand_priv_bytes_ex(OPENSSL_CTX *ctx, unsigned char *buf, int num);
 191
 192 /* Equivalent of RAND_bytes() but additionally taking an OPENSSL_CTX */
 193 int rand_bytes_ex(OPENSSL_CTX *ctx, unsigned char *buf, int num);
 194
 195 #endif