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