1 | /* |
2 | * ccdrbg.h |
3 | * corecrypto |
4 | * |
5 | * Created on 08/17/2010 |
6 | * |
7 | * Copyright (c) 2010,2011,2012,2014,2015 Apple Inc. All rights reserved. |
8 | * |
9 | */ |
10 | |
11 | /*! |
12 | @header corecrypto/ccdrbg.h |
13 | @abstract The functions provided in ccdrbg.h implement high-level accessors |
14 | to cryptographically secure random numbers. |
15 | |
16 | */ |
17 | |
18 | #ifndef _CORECRYPTO_CCDRBG_H_ |
19 | #define _CORECRYPTO_CCDRBG_H_ |
20 | |
21 | #include <corecrypto/cc.h> |
22 | #include <corecrypto/ccdrbg_impl.h> |
23 | |
24 | /* |
25 | * The maximum length of the entropy_input, additional_input (max_additional_input_length) , personalization string |
26 | * (max_personalization_string_length) and max_number_of_bits_per_request are implementation dependent |
27 | * but shall fit in a 32 bit register and be be less than or equal to the specified maximum length for the |
28 | * selected DRBG mechanism (NIST 800-90A Section 10). |
29 | */ |
30 | |
31 | #define CCDRBG_MAX_ENTROPY_SIZE ((uint32_t)1<<16) |
32 | #define CCDRBG_MAX_ADDITIONALINPUT_SIZE ((uint32_t)1<<16) |
33 | #define CCDRBG_MAX_PSINPUT_SIZE ((uint32_t)1<<16) |
34 | #define CCDRBG_MAX_REQUEST_SIZE ((uint32_t)1<<16) //this is the absolute maximum in NIST 800-90A |
35 | #define CCDRBG_RESEED_INTERVAL ((uint64_t)1<<30) // must be able to fit the NIST maximum of 2^48 |
36 | |
37 | |
38 | /* |
39 | * The entropyLength is forced to be greater or equal than the security strength. |
40 | * Nonce is not forced. It either needs to have 0.5*security strength entropy. Or, a vale that is repeated |
41 | * less than a 0.5*security strength bit random string. |
42 | * see below or NIST 800-90A for the definition of security strength |
43 | */ |
44 | |
45 | CC_INLINE int ccdrbg_init(const struct ccdrbg_info *info, |
46 | struct ccdrbg_state *drbg, |
47 | size_t entropyLength, const void* entropy, |
48 | size_t nonceLength, const void* nonce, |
49 | size_t psLength, const void* ps) |
50 | { |
51 | return info->init(info, drbg, entropyLength, entropy, nonceLength, nonce, psLength, ps); |
52 | } |
53 | |
54 | /* |
55 | * The entropyLength is forced to be greater or equal than the security strength. |
56 | */ |
57 | CC_INLINE int ccdrbg_reseed(const struct ccdrbg_info *info, |
58 | struct ccdrbg_state *drbg, |
59 | size_t entropyLength, const void *entropy, |
60 | size_t additionalLength, const void *additional) |
61 | { |
62 | return info->reseed(drbg, entropyLength, entropy, additionalLength, additional); |
63 | } |
64 | |
65 | |
66 | CC_INLINE int ccdrbg_generate(const struct ccdrbg_info *info, |
67 | struct ccdrbg_state *drbg, |
68 | size_t dataOutLength, void *dataOut, |
69 | size_t additionalLength, const void *additional) |
70 | { |
71 | return info->generate(drbg, dataOutLength, dataOut, additionalLength, additional); |
72 | } |
73 | |
74 | CC_INLINE void ccdrbg_done(const struct ccdrbg_info *info, |
75 | struct ccdrbg_state *drbg) |
76 | { |
77 | info->done(drbg); |
78 | } |
79 | |
80 | CC_INLINE size_t ccdrbg_context_size(const struct ccdrbg_info *info) |
81 | { |
82 | return info->size; |
83 | } |
84 | |
85 | |
86 | /* |
87 | * NIST SP 800-90 CTR_DRBG |
88 | * the maximum security strengh of drbg equals to the block size of the corresponding ECB. |
89 | */ |
90 | struct ccdrbg_nistctr_custom { |
91 | const struct ccmode_ctr *ctr_info; |
92 | size_t keylen; |
93 | int strictFIPS; |
94 | int use_df; |
95 | }; |
96 | |
97 | void ccdrbg_factory_nistctr(struct ccdrbg_info *info, const struct ccdrbg_nistctr_custom *custom); |
98 | |
99 | /* |
100 | * NIST SP 800-90 HMAC_DRBG |
101 | * the maximum security strengh of drbg is half of output size of the input hash function and it internally is limited to 256 bits |
102 | */ |
103 | struct ccdrbg_nisthmac_custom { |
104 | const struct ccdigest_info *di; |
105 | int strictFIPS; |
106 | }; |
107 | |
108 | void ccdrbg_factory_nisthmac(struct ccdrbg_info *info, const struct ccdrbg_nisthmac_custom *custom); |
109 | |
110 | #endif /* _CORECRYPTO_CCDRBG_H_ */ |
111 | |