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; 142 EVP_CIPHER_CTX *ctx_df; 143 const EVP_CIPHER *cipher; 144 size_t keylen; 145 unsigned char K[32]; 146 unsigned char V[16]; 147 /* Temporary block storage used by ctr_df */ 148 unsigned char bltmp[16]; 149 size_t bltmp_pos; 150 unsigned char KX[48]; 151 } RAND_DRBG_CTR; 152 153 154 /* 155 * The 'random pool' acts as a dumb container for collecting random 156 * input from various entropy sources. The pool has no knowledge about 157 * whether its randomness is fed into a legacy RAND_METHOD via RAND_add() 158 * or into a new style RAND_DRBG. It is the callers duty to 1) initialize the 159 * random pool, 2) pass it to the polling callbacks, 3) seed the RNG, and 160 * 4) cleanup the random pool again. 161 * 162 * The random pool contains no locking mechanism because its scope and 163 * lifetime is intended to be restricted to a single stack frame. 164 */ 165 struct rand_pool_st { 166 unsigned char *buffer; /* points to the beginning of the random pool */ 167 size_t len; /* current number of random bytes contained in the pool */ 168 169 int attached; /* true pool was attached to existing buffer */ 170 int secure; /* 1: allocated on the secure heap, 0: otherwise */ 171 172 size_t min_len; /* minimum number of random bytes requested */ 173 size_t max_len; /* maximum number of random bytes (allocated buffer size) */ 174 size_t alloc_len; /* current number of bytes allocated */ 175 size_t entropy; /* current entropy count in bits */ 176 size_t entropy_requested; /* requested entropy count in bits */ 177 }; 178 179 /* 180 * The state of all types of DRBGs, even though we only have CTR mode 181 * right now. 182 */ 183 struct rand_drbg_st { 184 CRYPTO_RWLOCK *lock; 185 RAND_DRBG *parent; 186 int secure; /* 1: allocated on the secure heap, 0: otherwise */ 187 int type; /* the nid of the underlying algorithm */ 188 /* 189 * Stores the return value of openssl_get_fork_id() as of when we last 190 * reseeded. The DRBG reseeds automatically whenever drbg->fork_id != 191 * openssl_get_fork_id(). Used to provide fork-safety and reseed this 192 * DRBG in the child process. 193 */ 194 int fork_id; 195 unsigned short flags; /* various external flags */ 196 197 /* 198 * The random_data is used by RAND_add()/drbg_add() to attach random 199 * data to the global drbg, such that the rand_drbg_get_entropy() callback 200 * can pull it during instantiation and reseeding. This is necessary to 201 * reconcile the different philosophies of the RAND and the RAND_DRBG 202 * with respect to how randomness is added to the RNG during reseeding 203 * (see PR #4328). 204 */ 205 struct rand_pool_st *seed_pool; 206 207 /* 208 * Auxiliary pool for additional data. 209 */ 210 struct rand_pool_st *adin_pool; 211 212 /* 213 * The following parameters are setup by the per-type "init" function. 214 * 215 * Currently the only type is CTR_DRBG, its init function is drbg_ctr_init(). 216 * 217 * The parameters are closely related to the ones described in 218 * section '10.2.1 CTR_DRBG' of [NIST SP 800-90Ar1], with one 219 * crucial difference: In the NIST standard, all counts are given 220 * in bits, whereas in OpenSSL entropy counts are given in bits 221 * and buffer lengths are given in bytes. 222 * 223 * Since this difference has lead to some confusion in the past, 224 * (see [GitHub Issue #2443], formerly [rt.openssl.org #4055]) 225 * the 'len' suffix has been added to all buffer sizes for 226 * clarification. 227 */ 228 229 int strength; 230 size_t max_request; 231 size_t min_entropylen, max_entropylen; 232 size_t min_noncelen, max_noncelen; 233 size_t max_perslen, max_adinlen; 234 235 /* Counts the number of generate requests since the last reseed. */ 236 unsigned int reseed_gen_counter; 237 /* 238 * Maximum number of generate requests until a reseed is required. 239 * This value is ignored if it is zero. 240 */ 241 unsigned int reseed_interval; 242 /* Stores the time when the last reseeding occurred */ 243 time_t reseed_time; 244 /* 245 * Specifies the maximum time interval (in seconds) between reseeds. 246 * This value is ignored if it is zero. 247 */ 248 time_t reseed_time_interval; 249 /* 250 * Counts the number of reseeds since instantiation. 251 * This value is ignored if it is zero. 252 * 253 * This counter is used only for seed propagation from the <master> DRBG 254 * to its two children, the <public> and <private> DRBG. This feature is 255 * very special and its sole purpose is to ensure that any randomness which 256 * is added by RAND_add() or RAND_seed() will have an immediate effect on 257 * the output of RAND_bytes() resp. RAND_priv_bytes(). 258 */ 259 TSAN_QUALIFIER unsigned int reseed_prop_counter; 260 unsigned int reseed_next_counter; 261 262 size_t seedlen; 263 DRBG_STATUS state; 264 265 /* Application data, mainly used in the KATs. */ 266 CRYPTO_EX_DATA ex_data; 267 268 /* Implementation specific data (currently only one implementation) */ 269 union { 270 RAND_DRBG_CTR ctr; 271 } data; 272 273 /* Implementation specific methods */ 274 RAND_DRBG_METHOD *meth; 275 276 /* Callback functions. See comments in rand_lib.c */ 277 RAND_DRBG_get_entropy_fn get_entropy; 278 RAND_DRBG_cleanup_entropy_fn cleanup_entropy; 279 RAND_DRBG_get_nonce_fn get_nonce; 280 RAND_DRBG_cleanup_nonce_fn cleanup_nonce; 281 }; 282 283 /* The global RAND method, and the global buffer and DRBG instance. */ 284 extern RAND_METHOD rand_meth; 285 286 /* DRBG helpers */ 287 int rand_drbg_restart(RAND_DRBG *drbg, 288 const unsigned char *buffer, size_t len, size_t entropy); 289 size_t rand_drbg_seedlen(RAND_DRBG *drbg); 290 /* locking api */ 291 int rand_drbg_lock(RAND_DRBG *drbg); 292 int rand_drbg_unlock(RAND_DRBG *drbg); 293 int rand_drbg_enable_locking(RAND_DRBG *drbg); 294 295 296 /* initializes the AES-CTR DRBG implementation */ 297 int drbg_ctr_init(RAND_DRBG *drbg); 298 299 #endif 300