1RAND_DRBG_NEW(3)                    OpenSSL                   RAND_DRBG_NEW(3)
2
3
4

NAME

6       RAND_DRBG_new, RAND_DRBG_secure_new, RAND_DRBG_set,
7       RAND_DRBG_set_defaults, RAND_DRBG_instantiate, RAND_DRBG_uninstantiate,
8       RAND_DRBG_free - initialize and cleanup a RAND_DRBG instance
9

SYNOPSIS

11        #include <openssl/rand_drbg.h>
12
13
14        RAND_DRBG *RAND_DRBG_new(int type,
15                                 unsigned int flags,
16                                 RAND_DRBG *parent);
17
18        RAND_DRBG *RAND_DRBG_secure_new(int type,
19                                        unsigned int flags,
20                                        RAND_DRBG *parent);
21
22        int RAND_DRBG_set(RAND_DRBG *drbg,
23                          int type, unsigned int flags);
24
25        int RAND_DRBG_set_defaults(int type, unsigned int flags);
26
27        int RAND_DRBG_instantiate(RAND_DRBG *drbg,
28                                  const unsigned char *pers, size_t perslen);
29
30        int RAND_DRBG_uninstantiate(RAND_DRBG *drbg);
31
32        void RAND_DRBG_free(RAND_DRBG *drbg);
33

DESCRIPTION

35       RAND_DRBG_new() and RAND_DRBG_secure_new() create a new DRBG instance
36       of the given type, allocated from the heap resp.  the secure heap
37       (using OPENSSL_zalloc() resp. OPENSSL_secure_zalloc()).
38
39       RAND_DRBG_set() initializes the drbg with the given type and flags.
40
41       RAND_DRBG_set_defaults() sets the default type and flags for new DRBG
42       instances.
43
44       Currently, all DRBG types are based on AES-CTR, so type can be one of
45       the following values: NID_aes_128_ctr, NID_aes_192_ctr,
46       NID_aes_256_ctr.  Before the DRBG can be used to generate random bits,
47       it is necessary to set its type and to instantiate it.
48
49       The optional flags argument specifies a set of bit flags which can be
50       joined using the | operator. Currently, the only flag is
51       RAND_DRBG_FLAG_CTR_NO_DF, which disables the use of the derivation
52       function ctr_df. For an explanation, see [NIST SP 800-90A Rev. 1].
53
54       If a parent instance is specified then this will be used instead of the
55       default entropy source for reseeding the drbg. It is said that the drbg
56       is chained to its parent.  For more information, see the NOTES section.
57
58       RAND_DRBG_instantiate() seeds the drbg instance using random input from
59       trusted entropy sources.  Optionally, a personalization string pers of
60       length perslen can be specified.  To omit the personalization string,
61       set pers=NULL and perslen=0;
62
63       RAND_DRBG_uninstantiate() clears the internal state of the drbg and
64       puts it back in the uninstantiated state.
65

RETURN VALUES

67       RAND_DRBG_new() and RAND_DRBG_secure_new() return a pointer to a DRBG
68       instance allocated on the heap, resp. secure heap.
69
70       RAND_DRBG_set(), RAND_DRBG_instantiate(), and RAND_DRBG_uninstantiate()
71       return 1 on success, and 0 on failure.
72
73       RAND_DRBG_free() does not return a value.
74

NOTES

76       The DRBG design supports chaining, which means that a DRBG instance can
77       use another parent DRBG instance instead of the default entropy source
78       to obtain fresh random input for reseeding, provided that parent DRBG
79       instance was properly instantiated, either from a trusted entropy
80       source, or from yet another parent DRBG instance.  For a detailed
81       description of the reseeding process, see RAND_DRBG(7).
82
83       The default DRBG type and flags are applied only during creation of a
84       DRBG instance.  To ensure that they are applied to the global and
85       thread-local DRBG instances (<master>, resp. <public> and <private>),
86       it is necessary to call RAND_DRBG_set_defaults() before creating any
87       thread and before calling any cryptographic routines that obtain random
88       data directly or indirectly.
89

SEE ALSO

91       OPENSSL_zalloc(3), OPENSSL_secure_zalloc(3), RAND_DRBG_generate(3),
92       RAND_DRBG(7)
93

HISTORY

95       The RAND_DRBG functions were added in OpenSSL 1.1.1.
96

98       Copyright 2017-2020 The OpenSSL Project Authors. All Rights Reserved.
99
100       Licensed under the OpenSSL license (the "License").  You may not use
101       this file except in compliance with the License.  You can obtain a copy
102       in the file LICENSE in the source distribution or at
103       <https://www.openssl.org/source/license.html>.
104
105
106
1071.1.1q                            2023-07-20                  RAND_DRBG_NEW(3)
Impressum