3ff98ae0526a62dd29b97b258e48275b647f5335
[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(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
53 RAND_DRBG_new_ex() and RAND_DRBG_secure_new_ex()
54 create a new DRBG instance of the given B<type>, allocated from the heap resp.
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.
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
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
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.
75
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
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
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>).
103
104 =back
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
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.
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
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
159 =head1 HISTORY
160
161 The RAND_DRBG functions were added in OpenSSL 1.1.1.
162
163 =head1 COPYRIGHT
164
165 Copyright 2017-2019 The OpenSSL Project Authors. All Rights Reserved.
166
167 Licensed under the Apache License 2.0 (the "License").  You may not use
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