]>
Commit | Line | Data |
---|---|---|
a73d990e DMSP |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
37ca204b | 5 | RAND_DRBG_new_ex, |
a73d990e | 6 | RAND_DRBG_new, |
37ca204b | 7 | RAND_DRBG_secure_new_ex, |
a73d990e DMSP |
8 | RAND_DRBG_secure_new, |
9 | RAND_DRBG_set, | |
10 | RAND_DRBG_set_defaults, | |
11 | RAND_DRBG_instantiate, | |
12 | RAND_DRBG_uninstantiate, | |
13 | RAND_DRBG_free | |
14 | - initialize and cleanup a RAND_DRBG instance | |
15 | ||
16 | =head1 SYNOPSIS | |
17 | ||
18 | #include <openssl/rand_drbg.h> | |
19 | ||
37ca204b MC |
20 | RAND_DRBG *RAND_DRBG_new_ex(OPENSSL_CTX *ctx, |
21 | int type, | |
22 | unsigned int flags, | |
23 | RAND_DRBG *parent); | |
a73d990e DMSP |
24 | |
25 | RAND_DRBG *RAND_DRBG_new(int type, | |
26 | unsigned int flags, | |
27 | RAND_DRBG *parent); | |
28 | ||
37ca204b MC |
29 | RAND_DRBG *RAND_DRBG_secure_new_ex(OPENSSL_CTX *ctx, |
30 | int type, | |
31 | unsigned int flags, | |
32 | RAND_DRBG *parent); | |
33 | ||
a73d990e DMSP |
34 | RAND_DRBG *RAND_DRBG_secure_new(int type, |
35 | unsigned int flags, | |
36 | RAND_DRBG *parent); | |
37 | ||
38 | int RAND_DRBG_set(RAND_DRBG *drbg, | |
39 | int type, unsigned int flags); | |
40 | ||
41 | int RAND_DRBG_set_defaults(int type, unsigned int flags); | |
42 | ||
43 | int RAND_DRBG_instantiate(RAND_DRBG *drbg, | |
44 | const unsigned char *pers, size_t perslen); | |
45 | ||
46 | int RAND_DRBG_uninstantiate(RAND_DRBG *drbg); | |
47 | ||
48 | void RAND_DRBG_free(RAND_DRBG *drbg); | |
49 | ||
50 | ||
51 | =head1 DESCRIPTION | |
52 | ||
37ca204b | 53 | RAND_DRBG_new_ex() and RAND_DRBG_secure_new_ex() |
a73d990e | 54 | create a new DRBG instance of the given B<type>, allocated from the heap resp. |
37ca204b MC |
55 | the secure heap, for the given OPENSSL_CTX <ctx> |
56 | (using OPENSSL_zalloc() resp. OPENSSL_secure_zalloc()). The <ctx> parameter can | |
57 | be NULL in which case the default OPENSSL_CTX is used. RAND_DRBG_new() and | |
58 | RAND_DRBG_secure_new() are the same as RAND_DRBG_new_ex() and | |
59 | RAND_DRBG_secure_new_ex() except that the default OPENSSL_CTX is always used. | |
a73d990e DMSP |
60 | |
61 | RAND_DRBG_set() initializes the B<drbg> with the given B<type> and B<flags>. | |
62 | ||
63 | RAND_DRBG_set_defaults() sets the default B<type> and B<flags> for new DRBG | |
64 | instances. | |
65 | ||
8bf36651 SL |
66 | The DRBG types are AES-CTR, HMAC and HASH so B<type> can be one of the |
67 | following values: | |
68 | ||
69 | NID_aes_128_ctr, NID_aes_192_ctr, NID_aes_256_ctr, NID_sha1, NID_sha224, | |
70 | NID_sha256, NID_sha384, NID_sha512, NID_sha512_224, NID_sha512_256, | |
71 | NID_sha3_224, NID_sha3_256, NID_sha3_384 or NID_sha3_512. | |
72 | ||
f3002a2e SL |
73 | If this method is not called then the default type is given by NID_aes_256_ctr |
74 | and the default flags are zero. | |
8bf36651 | 75 | |
a73d990e DMSP |
76 | Before the DRBG can be used to generate random bits, it is necessary to set |
77 | its type and to instantiate it. | |
78 | ||
79 | The optional B<flags> argument specifies a set of bit flags which can be | |
8bf36651 SL |
80 | joined using the | operator. The supported flags are: |
81 | ||
82 | =over 4 | |
83 | ||
84 | =item RAND_DRBG_FLAG_CTR_NO_DF | |
85 | ||
86 | Disables the use of the derivation function ctr_df. For an explanation, | |
87 | see [NIST SP 800-90A Rev. 1]. | |
88 | ||
89 | =item RAND_DRBG_FLAG_HMAC | |
90 | ||
91 | Enables use of HMAC instead of the HASH DRBG. | |
92 | ||
93 | =item RAND_DRBG_FLAG_MASTER | |
94 | ||
95 | =item RAND_DRBG_FLAG_PUBLIC | |
96 | ||
97 | =item RAND_DRBG_FLAG_PRIVATE | |
98 | ||
99 | These 3 flags can be used to set the individual DRBG types created. Multiple | |
100 | calls are required to set the types to different values. If none of these 3 | |
f3002a2e SL |
101 | flags are used, then the same type and flags are used for all 3 DRBGs in the |
102 | B<drbg> chain (<master>, <public> and <private>). | |
8bf36651 SL |
103 | |
104 | =back | |
a73d990e DMSP |
105 | |
106 | If a B<parent> instance is specified then this will be used instead of | |
107 | the default entropy source for reseeding the B<drbg>. It is said that the | |
108 | B<drbg> is I<chained> to its B<parent>. | |
109 | For more information, see the NOTES section. | |
110 | ||
111 | ||
112 | RAND_DRBG_instantiate() | |
113 | seeds the B<drbg> instance using random input from trusted entropy sources. | |
114 | Optionally, a personalization string B<pers> of length B<perslen> can be | |
115 | specified. | |
116 | To omit the personalization string, set B<pers>=NULL and B<perslen>=0; | |
117 | ||
118 | RAND_DRBG_uninstantiate() | |
119 | clears the internal state of the B<drbg> and puts it back in the | |
120 | uninstantiated state. | |
121 | ||
122 | =head1 RETURN VALUES | |
123 | ||
124 | ||
37ca204b MC |
125 | RAND_DRBG_new_ex(), RAND_DRBG_new(), RAND_DRBG_secure_new_ex() and |
126 | RAND_DRBG_secure_new() return a pointer to a DRBG instance allocated on the | |
127 | heap, resp. secure heap. | |
a73d990e DMSP |
128 | |
129 | RAND_DRBG_set(), | |
130 | RAND_DRBG_instantiate(), and | |
131 | RAND_DRBG_uninstantiate() | |
132 | return 1 on success, and 0 on failure. | |
133 | ||
134 | RAND_DRBG_free() does not return a value. | |
135 | ||
136 | =head1 NOTES | |
137 | ||
138 | The DRBG design supports I<chaining>, which means that a DRBG instance can | |
139 | use another B<parent> DRBG instance instead of the default entropy source | |
140 | to obtain fresh random input for reseeding, provided that B<parent> DRBG | |
141 | instance was properly instantiated, either from a trusted entropy source, | |
142 | or from yet another parent DRBG instance. | |
143 | For a detailed description of the reseeding process, see L<RAND_DRBG(7)>. | |
144 | ||
145 | The default DRBG type and flags are applied only during creation of a DRBG | |
146 | instance. | |
147 | To ensure that they are applied to the global and thread-local DRBG instances | |
148 | (<master>, resp. <public> and <private>), it is necessary to call | |
149 | RAND_DRBG_set_defaults() before creating any thread and before calling any | |
150 | cryptographic routines that obtain random data directly or indirectly. | |
151 | ||
a73d990e DMSP |
152 | =head1 SEE ALSO |
153 | ||
154 | L<OPENSSL_zalloc(3)>, | |
155 | L<OPENSSL_secure_zalloc(3)>, | |
156 | L<RAND_DRBG_generate(3)>, | |
157 | L<RAND_DRBG(7)> | |
158 | ||
b5c4bbbe JL |
159 | =head1 HISTORY |
160 | ||
161 | The RAND_DRBG functions were added in OpenSSL 1.1.1. | |
162 | ||
a73d990e DMSP |
163 | =head1 COPYRIGHT |
164 | ||
b5c4bbbe | 165 | Copyright 2017-2019 The OpenSSL Project Authors. All Rights Reserved. |
a73d990e | 166 | |
4746f25a | 167 | Licensed under the Apache License 2.0 (the "License"). You may not use |
a73d990e DMSP |
168 | this file except in compliance with the License. You can obtain a copy |
169 | in the file LICENSE in the source distribution or at | |
170 | L<https://www.openssl.org/source/license.html>. | |
171 | ||
172 | =cut |