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
45CC_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 */
57CC_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
66CC_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
74CC_INLINE void ccdrbg_done(const struct ccdrbg_info *info,
75 struct ccdrbg_state *drbg)
76{
77 info->done(drbg);
78}
79
80CC_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 */
90struct ccdrbg_nistctr_custom {
91 const struct ccmode_ctr *ctr_info;
92 size_t keylen;
93 int strictFIPS;
94 int use_df;
95};
96
97void 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 */
103struct ccdrbg_nisthmac_custom {
104 const struct ccdigest_info *di;
105 int strictFIPS;
106};
107
108void ccdrbg_factory_nisthmac(struct ccdrbg_info *info, const struct ccdrbg_nisthmac_custom *custom);
109
110#endif /* _CORECRYPTO_CCDRBG_H_ */
111