1 /* Copyright (c) (2010-2012,2014-2019,2021,2022) Apple Inc. All rights reserved. 2 * 3 * corecrypto is licensed under Apple Inc.’s Internal Use License Agreement (which 4 * is contained in the License.txt file distributed with corecrypto) and only to 5 * people who accept that license. IMPORTANT: Any license rights granted to you by 6 * Apple Inc. (if any) are limited to internal use within your organization only on 7 * devices and computers you own or control, for the sole purpose of verifying the 8 * security characteristics and correct functioning of the Apple Software. You may 9 * not, directly or indirectly, redistribute the Apple Software or any portions thereof. 10 */ 11 12 /*! 13 @header corecrypto/ccdrbg.h 14 @abstract The functions provided in ccdrbg.h implement high-level accessors 15 to cryptographically secure random numbers. 16 17 */ 18 19 #ifndef _CORECRYPTO_CCDRBG_H_ 20 #define _CORECRYPTO_CCDRBG_H_ 21 22 #include <corecrypto/cc.h> 23 #include <corecrypto/ccdrbg_impl.h> 24 #include <corecrypto/ccdrbg_df.h> 25 26 /* 27 * The maximum length of the entropy_input, additional_input (max_additional_input_length) , personalization string 28 * (max_personalization_string_length) and max_number_of_bits_per_request are implementation dependent 29 * but shall fit in a 32 bit register and be be less than or equal to the specified maximum length for the 30 * selected DRBG mechanism (NIST 800-90A Section 10). 31 */ 32 33 #define CCDRBG_MAX_ENTROPY_SIZE ((uint32_t)1<<16) 34 #define CCDRBG_MAX_ADDITIONALINPUT_SIZE ((uint32_t)1<<16) 35 #define CCDRBG_MAX_PSINPUT_SIZE ((uint32_t)1<<16) 36 #define CCDRBG_MAX_REQUEST_SIZE ((uint32_t)1<<16) //this is the absolute maximum in NIST 800-90A 37 #define CCDRBG_RESEED_INTERVAL ((uint64_t)1<<48) // must be able to fit the NIST maximum of 2^48 38 39 40 /* 41 * The entropyLength is forced to be greater or equal than the security strength. 42 * Nonce is not forced. It either needs to have 0.5*security strength entropy. Or, a vale that is repeated 43 * less than a 0.5*security strength bit random string. 44 * see below or NIST 800-90A for the definition of security strength 45 */ 46 47 int ccdrbg_init(const struct ccdrbg_info *info, 48 struct ccdrbg_state *drbg, 49 size_t entropyLength, const void* entropy, 50 size_t nonceLength, const void* nonce, 51 size_t psLength, const void* ps); 52 53 /* 54 * The entropyLength is forced to be greater or equal than the security strength. 55 */ 56 int ccdrbg_reseed(const struct ccdrbg_info *info, 57 struct ccdrbg_state *drbg, 58 size_t entropyLength, const void *entropy, 59 size_t additionalLength, const void *additional); 60 61 62 int ccdrbg_generate(const struct ccdrbg_info *info, 63 struct ccdrbg_state *drbg, 64 size_t dataOutLength, void *dataOut, 65 size_t additionalLength, const void *additional); 66 67 void ccdrbg_done(const struct ccdrbg_info *info, 68 struct ccdrbg_state *drbg); 69 70 size_t ccdrbg_context_size(const struct ccdrbg_info *info); 71 72 /*! 73 @function ccdrbg_must_reseed 74 @abstract Whether the DRBG requires a reseed to continue generation 75 @param info The DRBG implementation descriptor 76 @param drbg The DRBG state 77 @return true if the DRBG requires reseed; false otherwise 78 79 @discussion In strict FIPS mode, this returns true after a count of 80 requests exceeding the DRBG reseed interval of 2^48. When strict 81 FIPS mode is disabled, this function always returns false. 82 */ 83 bool ccdrbg_must_reseed(const struct ccdrbg_info *info, 84 const struct ccdrbg_state *drbg); 85 86 87 /* 88 * NIST SP 800-90 CTR_DRBG 89 * the maximum security strengh of drbg equals to the block size of the corresponding ECB. 90 */ 91 struct ccdrbg_nistctr_custom { 92 const struct ccmode_ctr *ctr_info; 93 size_t keylen; 94 int strictFIPS; 95 const ccdrbg_df_ctx_t *df_ctx; 96 }; 97 98 void ccdrbg_factory_nistctr(struct ccdrbg_info *info, const struct ccdrbg_nistctr_custom *custom); 99 100 /* 101 * NIST SP 800-90 HMAC_DRBG 102 * the maximum security strengh of drbg is half of output size of the input hash function and it internally is limited to 256 bits 103 */ 104 struct ccdrbg_nisthmac_custom { 105 const struct ccdigest_info *di; 106 int strictFIPS; 107 }; 108 109 void ccdrbg_factory_nisthmac(struct ccdrbg_info *info, const struct ccdrbg_nisthmac_custom *custom); 110 111 #endif /* _CORECRYPTO_CCDRBG_H_ */ 112