• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1=pod
2
3=head1 NAME
4
5RAND_DRBG_new,
6RAND_DRBG_secure_new,
7RAND_DRBG_set,
8RAND_DRBG_set_defaults,
9RAND_DRBG_instantiate,
10RAND_DRBG_uninstantiate,
11RAND_DRBG_free
12- initialize and cleanup a RAND_DRBG instance
13
14=head1 SYNOPSIS
15
16 #include <openssl/rand_drbg.h>
17
18
19 RAND_DRBG *RAND_DRBG_new(int type,
20                          unsigned int flags,
21                          RAND_DRBG *parent);
22
23 RAND_DRBG *RAND_DRBG_secure_new(int type,
24                                 unsigned int flags,
25                                 RAND_DRBG *parent);
26
27 int RAND_DRBG_set(RAND_DRBG *drbg,
28                   int type, unsigned int flags);
29
30 int RAND_DRBG_set_defaults(int type, unsigned int flags);
31
32 int RAND_DRBG_instantiate(RAND_DRBG *drbg,
33                           const unsigned char *pers, size_t perslen);
34
35 int RAND_DRBG_uninstantiate(RAND_DRBG *drbg);
36
37 void RAND_DRBG_free(RAND_DRBG *drbg);
38
39
40=head1 DESCRIPTION
41
42RAND_DRBG_new() and RAND_DRBG_secure_new()
43create a new DRBG instance of the given B<type>, allocated from the heap resp.
44the secure heap
45(using OPENSSL_zalloc() resp. OPENSSL_secure_zalloc()).
46
47RAND_DRBG_set() initializes the B<drbg> with the given B<type> and B<flags>.
48
49RAND_DRBG_set_defaults() sets the default B<type> and B<flags> for new DRBG
50instances.
51
52Currently, all DRBG types are based on AES-CTR, so B<type> can be one of the
53following values: NID_aes_128_ctr, NID_aes_192_ctr, NID_aes_256_ctr.
54Before the DRBG can be used to generate random bits, it is necessary to set
55its type and to instantiate it.
56
57The optional B<flags> argument specifies a set of bit flags which can be
58joined using the | operator. Currently, the only flag is
59RAND_DRBG_FLAG_CTR_NO_DF, which disables the use of the derivation function
60ctr_df. For an explanation, see [NIST SP 800-90A Rev. 1].
61
62If a B<parent> instance is specified then this will be used instead of
63the default entropy source for reseeding the B<drbg>. It is said that the
64B<drbg> is I<chained> to its B<parent>.
65For more information, see the NOTES section.
66
67
68RAND_DRBG_instantiate()
69seeds the B<drbg> instance using random input from trusted entropy sources.
70Optionally, a personalization string B<pers> of length B<perslen> can be
71specified.
72To omit the personalization string, set B<pers>=NULL and B<perslen>=0;
73
74RAND_DRBG_uninstantiate()
75clears the internal state of the B<drbg> and puts it back in the
76uninstantiated state.
77
78=head1 RETURN VALUES
79
80
81RAND_DRBG_new() and RAND_DRBG_secure_new() return a pointer to a DRBG
82instance allocated on the heap, resp. secure heap.
83
84RAND_DRBG_set(),
85RAND_DRBG_instantiate(), and
86RAND_DRBG_uninstantiate()
87return 1 on success, and 0 on failure.
88
89RAND_DRBG_free() does not return a value.
90
91=head1 NOTES
92
93The DRBG design supports I<chaining>, which means that a DRBG instance can
94use another B<parent> DRBG instance instead of the default entropy source
95to obtain fresh random input for reseeding, provided that B<parent> DRBG
96instance was properly instantiated, either from a trusted entropy source,
97or from yet another parent DRBG instance.
98For a detailed description of the reseeding process, see L<RAND_DRBG(7)>.
99
100The default DRBG type and flags are applied only during creation of a DRBG
101instance.
102To ensure that they are applied to the global and thread-local DRBG instances
103(<master>, resp. <public> and <private>), it is necessary to call
104RAND_DRBG_set_defaults() before creating any thread and before calling any
105cryptographic routines that obtain random data directly or indirectly.
106
107=head1 SEE ALSO
108
109L<OPENSSL_zalloc(3)>,
110L<OPENSSL_secure_zalloc(3)>,
111L<RAND_DRBG_generate(3)>,
112L<RAND_DRBG(7)>
113
114=head1 HISTORY
115
116The RAND_DRBG functions were added in OpenSSL 1.1.1.
117
118=head1 COPYRIGHT
119
120Copyright 2017-2020 The OpenSSL Project Authors. All Rights Reserved.
121
122Licensed under the OpenSSL license (the "License").  You may not use
123this file except in compliance with the License.  You can obtain a copy
124in the file LICENSE in the source distribution or at
125L<https://www.openssl.org/source/license.html>.
126
127=cut
128