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 | |