1 /* 2 * Copyright 1995-2020 The OpenSSL Project Authors. All Rights Reserved. 3 * 4 * Licensed under the OpenSSL license (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 21 # include "internal/numbers.h" 22 23 /* How many times to read the TSC as a randomness source. */ 24 # define TSC_READ_COUNT 4 25 26 /* Maximum reseed intervals */ 27 # define MAX_RESEED_INTERVAL (1 << 24) 28 # define MAX_RESEED_TIME_INTERVAL (1 << 20) /* approx. 12 days */ 29 30 /* Default reseed intervals */ 31 # define MASTER_RESEED_INTERVAL (1 << 8) 32 # define SLAVE_RESEED_INTERVAL (1 << 16) 33 # define MASTER_RESEED_TIME_INTERVAL (60*60) /* 1 hour */ 34 # define SLAVE_RESEED_TIME_INTERVAL (7*60) /* 7 minutes */ 35 36 37 38 /* 39 * Maximum input size for the DRBG (entropy, nonce, personalization string) 40 * 41 * NIST SP800 90Ar1 allows a maximum of (1 << 35) bits i.e., (1 << 32) bytes. 42 * 43 * We lower it to 'only' INT32_MAX bytes, which is equivalent to 2 gigabytes. 44 */ 45 # define DRBG_MAX_LENGTH INT32_MAX 46 47 48 /* 49 * Maximum allocation size for RANDOM_POOL buffers 50 * 51 * The max_len value for the buffer provided to the rand_drbg_get_entropy() 52 * callback is currently 2^31 bytes (2 gigabytes), if a derivation function 53 * is used. Since this is much too large to be allocated, the rand_pool_new() 54 * function chooses more modest values as default pool length, bounded 55 * by RAND_POOL_MIN_LENGTH and RAND_POOL_MAX_LENGTH 56 * 57 * The choice of the RAND_POOL_FACTOR is large enough such that the 58 * RAND_POOL can store a random input which has a lousy entropy rate of 59 * 8/256 (= 0.03125) bits per byte. This input will be sent through the 60 * derivation function which 'compresses' the low quality input into a 61 * high quality output. 62 * 63 * The factor 1.5 below is the pessimistic estimate for the extra amount 64 * of entropy required when no get_nonce() callback is defined. 65 */ 66 # define RAND_POOL_FACTOR 256 67 # define RAND_POOL_MAX_LENGTH (RAND_POOL_FACTOR * \ 68 3 * (RAND_DRBG_STRENGTH / 16)) 69 /* 70 * = (RAND_POOL_FACTOR * \ 71 * 1.5 * (RAND_DRBG_STRENGTH / 8)) 72 */ 73 74 /* 75 * Initial allocation minimum. 76 * 77 * There is a distinction between the secure and normal allocation minimums. 78 * Ideally, the secure allocation size should be a power of two. The normal 79 * allocation size doesn't have any such restriction. 80 * 81 * The secure value is based on 128 bits of secure material, which is 16 bytes. 82 * Typically, the DRBGs will set a minimum larger than this so optimal 83 * allocation ought to take place (for full quality seed material). 84 * 85 * The normal value has been chosen by noticing that the rand_drbg_get_nonce 86 * function is usually the largest of the built in allocation (twenty four 87 * bytes and then appending another sixteen bytes). This means the buffer ends 88 * with 40 bytes. The value of forty eight is comfortably above this which 89 * allows some slack in the platform specific values used. 90 */ 91 # define RAND_POOL_MIN_ALLOCATION(secure) ((secure) ? 16 : 48) 92 93 /* DRBG status values */ 94 typedef enum drbg_status_e { 95 DRBG_UNINITIALISED, 96 DRBG_READY, 97 DRBG_ERROR 98 } DRBG_STATUS; 99 100 101 /* instantiate */ 102 typedef int (*RAND_DRBG_instantiate_fn)(RAND_DRBG *ctx, 103 const unsigned char *ent, 104 size_t entlen, 105 const unsigned char *nonce, 106 size_t noncelen, 107 const unsigned char *pers, 108 size_t perslen); 109 /* reseed */ 110 typedef int (*RAND_DRBG_reseed_fn)(RAND_DRBG *ctx, 111 const unsigned char *ent, 112 size_t entlen, 113 const unsigned char *adin, 114 size_t adinlen); 115 /* generate output */ 116 typedef int (*RAND_DRBG_generate_fn)(RAND_DRBG *ctx, 117 unsigned char *out, 118 size_t outlen, 119 const unsigned char *adin, 120 size_t adinlen); 121 /* uninstantiate */ 122 typedef int (*RAND_DRBG_uninstantiate_fn)(RAND_DRBG *ctx); 123 124 125 /* 126 * The DRBG methods 127 */ 128 129 typedef struct rand_drbg_method_st { 130 RAND_DRBG_instantiate_fn instantiate; 131 RAND_DRBG_reseed_fn reseed; 132 RAND_DRBG_generate_fn generate; 133 RAND_DRBG_uninstantiate_fn uninstantiate; 134 } RAND_DRBG_METHOD; 135 136 137 /* 138 * The state of a DRBG AES-CTR. 139 */ 140 typedef struct rand_drbg_ctr_st { 141 EVP_CIPHER_CTX *ctx_ecb; 142 EVP_CIPHER_CTX *ctx_ctr; 143 EVP_CIPHER_CTX *ctx_df; 144 const EVP_CIPHER *cipher_ecb; 145 const EVP_CIPHER *cipher_ctr; 146 size_t keylen; 147 unsigned char K[32]; 148 unsigned char V[16]; 149 /* Temporary block storage used by ctr_df */ 150 unsigned char bltmp[16]; 151 size_t bltmp_pos; 152 unsigned char KX[48]; 153 } RAND_DRBG_CTR; 154 155 156 /* 157 * The 'random pool' acts as a dumb container for collecting random 158 * input from various entropy sources. The pool has no knowledge about 159 * whether its randomness is fed into a legacy RAND_METHOD via RAND_add() 160 * or into a new style RAND_DRBG. It is the callers duty to 1) initialize the 161 * random pool, 2) pass it to the polling callbacks, 3) seed the RNG, and 162 * 4) cleanup the random pool again. 163 * 164 * The random pool contains no locking mechanism because its scope and 165 * lifetime is intended to be restricted to a single stack frame. 166 */ 167 struct rand_pool_st { 168 unsigned char *buffer; /* points to the beginning of the random pool */ 169 size_t len; /* current number of random bytes contained in the pool */ 170 171 int attached; /* true pool was attached to existing buffer */ 172 int secure; /* 1: allocated on the secure heap, 0: otherwise */ 173 174 size_t min_len; /* minimum number of random bytes requested */ 175 size_t max_len; /* maximum number of random bytes (allocated buffer size) */ 176 size_t alloc_len; /* current number of bytes allocated */ 177 size_t entropy; /* current entropy count in bits */ 178 size_t entropy_requested; /* requested entropy count in bits */ 179 }; 180 181 /* 182 * The state of all types of DRBGs, even though we only have CTR mode 183 * right now. 184 */ 185 struct rand_drbg_st { 186 CRYPTO_RWLOCK *lock; 187 RAND_DRBG *parent; 188 int secure; /* 1: allocated on the secure heap, 0: otherwise */ 189 int type; /* the nid of the underlying algorithm */ 190 /* 191 * Stores the return value of openssl_get_fork_id() as of when we last 192 * reseeded. The DRBG reseeds automatically whenever drbg->fork_id != 193 * openssl_get_fork_id(). Used to provide fork-safety and reseed this 194 * DRBG in the child process. 195 */ 196 int fork_id; 197 unsigned short flags; /* various external flags */ 198 199 /* 200 * The random_data is used by RAND_add()/drbg_add() to attach random 201 * data to the global drbg, such that the rand_drbg_get_entropy() callback 202 * can pull it during instantiation and reseeding. This is necessary to 203 * reconcile the different philosophies of the RAND and the RAND_DRBG 204 * with respect to how randomness is added to the RNG during reseeding 205 * (see PR #4328). 206 */ 207 struct rand_pool_st *seed_pool; 208 209 /* 210 * Auxiliary pool for additional data. 211 */ 212 struct rand_pool_st *adin_pool; 213 214 /* 215 * The following parameters are setup by the per-type "init" function. 216 * 217 * Currently the only type is CTR_DRBG, its init function is drbg_ctr_init(). 218 * 219 * The parameters are closely related to the ones described in 220 * section '10.2.1 CTR_DRBG' of [NIST SP 800-90Ar1], with one 221 * crucial difference: In the NIST standard, all counts are given 222 * in bits, whereas in OpenSSL entropy counts are given in bits 223 * and buffer lengths are given in bytes. 224 * 225 * Since this difference has lead to some confusion in the past, 226 * (see [GitHub Issue #2443], formerly [rt.openssl.org #4055]) 227 * the 'len' suffix has been added to all buffer sizes for 228 * clarification. 229 */ 230 231 int strength; 232 size_t max_request; 233 size_t min_entropylen, max_entropylen; 234 size_t min_noncelen, max_noncelen; 235 size_t max_perslen, max_adinlen; 236 237 /* Counts the number of generate requests since the last reseed. */ 238 unsigned int generate_counter; 239 /* 240 * Maximum number of generate requests until a reseed is required. 241 * This value is ignored if it is zero. 242 */ 243 unsigned int reseed_interval; 244 /* Stores the time when the last reseeding occurred */ 245 time_t reseed_time; 246 /* 247 * Specifies the maximum time interval (in seconds) between reseeds. 248 * This value is ignored if it is zero. 249 */ 250 time_t reseed_time_interval; 251 252 /* 253 * Enables reseed propagation (see following comment) 254 */ 255 unsigned int enable_reseed_propagation; 256 257 /* 258 * Counts the number of reseeds since instantiation. 259 * This value is ignored if enable_reseed_propagation is zero. 260 * 261 * This counter is used only for seed propagation from the <master> DRBG 262 * to its two children, the <public> and <private> DRBG. This feature is 263 * very special and its sole purpose is to ensure that any randomness which 264 * is added by RAND_add() or RAND_seed() will have an immediate effect on 265 * the output of RAND_bytes() resp. RAND_priv_bytes(). 266 */ 267 TSAN_QUALIFIER unsigned int reseed_counter; 268 269 size_t seedlen; 270 DRBG_STATUS state; 271 272 /* Application data, mainly used in the KATs. */ 273 CRYPTO_EX_DATA ex_data; 274 275 /* Implementation specific data (currently only one implementation) */ 276 union { 277 RAND_DRBG_CTR ctr; 278 } data; 279 280 /* Implementation specific methods */ 281 RAND_DRBG_METHOD *meth; 282 283 /* Callback functions. See comments in rand_lib.c */ 284 RAND_DRBG_get_entropy_fn get_entropy; 285 RAND_DRBG_cleanup_entropy_fn cleanup_entropy; 286 RAND_DRBG_get_nonce_fn get_nonce; 287 RAND_DRBG_cleanup_nonce_fn cleanup_nonce; 288 }; 289 290 /* The global RAND method, and the global buffer and DRBG instance. */ 291 extern RAND_METHOD rand_meth; 292 293 /* DRBG helpers */ 294 int rand_drbg_restart(RAND_DRBG *drbg, 295 const unsigned char *buffer, size_t len, size_t entropy); 296 size_t rand_drbg_seedlen(RAND_DRBG *drbg); 297 /* locking api */ 298 int rand_drbg_lock(RAND_DRBG *drbg); 299 int rand_drbg_unlock(RAND_DRBG *drbg); 300 int rand_drbg_enable_locking(RAND_DRBG *drbg); 301 302 303 /* initializes the AES-CTR DRBG implementation */ 304 int drbg_ctr_init(RAND_DRBG *drbg); 305 306 #endif 307