1 /* Copyright (c) (2010,2011,2012,2014,2015,2016,2017,2018,2019) 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
25 /*
26 * The maximum length of the entropy_input, additional_input (max_additional_input_length) , personalization string
27 * (max_personalization_string_length) and max_number_of_bits_per_request are implementation dependent
28 * but shall fit in a 32 bit register and be be less than or equal to the specified maximum length for the
29 * selected DRBG mechanism (NIST 800-90A Section 10).
30 */
31
32 #define CCDRBG_MAX_ENTROPY_SIZE ((uint32_t)1<<16)
33 #define CCDRBG_MAX_ADDITIONALINPUT_SIZE ((uint32_t)1<<16)
34 #define CCDRBG_MAX_PSINPUT_SIZE ((uint32_t)1<<16)
35 #define CCDRBG_MAX_REQUEST_SIZE ((uint32_t)1<<16) //this is the absolute maximum in NIST 800-90A
36 #define CCDRBG_RESEED_INTERVAL ((uint64_t)1<<48) // must be able to fit the NIST maximum of 2^48
37
38
39 /*
40 * The entropyLength is forced to be greater or equal than the security strength.
41 * Nonce is not forced. It either needs to have 0.5*security strength entropy. Or, a vale that is repeated
42 * less than a 0.5*security strength bit random string.
43 * see below or NIST 800-90A for the definition of security strength
44 */
45
ccdrbg_init(const struct ccdrbg_info * info,struct ccdrbg_state * drbg,size_t entropyLength,const void * entropy,size_t nonceLength,const void * nonce,size_t psLength,const void * ps)46 CC_INLINE int ccdrbg_init(const struct ccdrbg_info *info,
47 struct ccdrbg_state *drbg,
48 size_t entropyLength, const void* entropy,
49 size_t nonceLength, const void* nonce,
50 size_t psLength, const void* ps)
51 {
52 return info->init(info, drbg, entropyLength, entropy, nonceLength, nonce, psLength, ps);
53 }
54
55 /*
56 * The entropyLength is forced to be greater or equal than the security strength.
57 */
ccdrbg_reseed(const struct ccdrbg_info * info,struct ccdrbg_state * drbg,size_t entropyLength,const void * entropy,size_t additionalLength,const void * additional)58 CC_INLINE int ccdrbg_reseed(const struct ccdrbg_info *info,
59 struct ccdrbg_state *drbg,
60 size_t entropyLength, const void *entropy,
61 size_t additionalLength, const void *additional)
62 {
63 return info->reseed(drbg, entropyLength, entropy, additionalLength, additional);
64 }
65
66
ccdrbg_generate(const struct ccdrbg_info * info,struct ccdrbg_state * drbg,size_t dataOutLength,void * dataOut,size_t additionalLength,const void * additional)67 CC_INLINE int ccdrbg_generate(const struct ccdrbg_info *info,
68 struct ccdrbg_state *drbg,
69 size_t dataOutLength, void *dataOut,
70 size_t additionalLength, const void *additional)
71 {
72 return info->generate(drbg, dataOutLength, dataOut, additionalLength, additional);
73 }
74
ccdrbg_done(const struct ccdrbg_info * info,struct ccdrbg_state * drbg)75 CC_INLINE void ccdrbg_done(const struct ccdrbg_info *info,
76 struct ccdrbg_state *drbg)
77 {
78 info->done(drbg);
79 }
80
ccdrbg_context_size(const struct ccdrbg_info * info)81 CC_INLINE size_t ccdrbg_context_size(const struct ccdrbg_info *info)
82 {
83 return info->size;
84 }
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 int use_df;
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