NAME

RAND_DRBG_new_ex, RAND_DRBG_new, RAND_DRBG_secure_new_ex, RAND_DRBG_secure_new, RAND_DRBG_set, RAND_DRBG_set_defaults, RAND_DRBG_instantiate, RAND_DRBG_uninstantiate, RAND_DRBG_free - initialize and cleanup a RAND_DRBG instance

SYNOPSIS

 #include <openssl/rand_drbg.h>
 
 RAND_DRBG *RAND_DRBG_new_ex(OPENSSL_CTX *ctx,
                             int type,
                             unsigned int flags,
                             RAND_DRBG *parent);
 
 RAND_DRBG *RAND_DRBG_new(int type,
                          unsigned int flags,
                          RAND_DRBG *parent);
 
 RAND_DRBG *RAND_DRBG_secure_new_ex(OPENSSL_CTX *ctx,
                                    int type,
                                    unsigned int flags,
                                    RAND_DRBG *parent);
 
 RAND_DRBG *RAND_DRBG_secure_new(int type,
                                 unsigned int flags,
                                 RAND_DRBG *parent);
 
 int RAND_DRBG_set(RAND_DRBG *drbg,
                   int type, unsigned int flags);
 
 int RAND_DRBG_set_defaults(int type, unsigned int flags);
 
 int RAND_DRBG_instantiate(RAND_DRBG *drbg,
                           const unsigned char *pers, size_t perslen);
 
 int RAND_DRBG_uninstantiate(RAND_DRBG *drbg);
 
 void RAND_DRBG_free(RAND_DRBG *drbg);

DESCRIPTION

RAND_DRBG_new_ex() and RAND_DRBG_secure_new_ex() create a new DRBG instance of the given type, allocated from the heap resp. the secure heap, for the given OPENSSL_CTX <ctx> (using OPENSSL_zalloc() resp. OPENSSL_secure_zalloc()). The <ctx> parameter can be NULL in which case the default OPENSSL_CTX is used. RAND_DRBG_new() and RAND_DRBG_secure_new() are the same as RAND_DRBG_new_ex() and RAND_DRBG_secure_new_ex() except that the default OPENSSL_CTX is always used.

RAND_DRBG_set() initializes the drbg with the given type and flags.

RAND_DRBG_set_defaults() sets the default type and flags for new DRBG instances.

The DRBG types are AES-CTR, HMAC and HASH so type can be one of the following values:

NID_aes_128_ctr, NID_aes_192_ctr, NID_aes_256_ctr, NID_sha1, NID_sha224, NID_sha256, NID_sha384, NID_sha512, NID_sha512_224, NID_sha512_256, NID_sha3_224, NID_sha3_256, NID_sha3_384 or NID_sha3_512.

If this method is not called then the default type is given by NID_aes_256_ctr and the default flags are zero.

Before the DRBG can be used to generate random bits, it is necessary to set its type and to instantiate it.

The optional flags argument specifies a set of bit flags which can be joined using the | operator. The supported flags are:

RAND_DRBG_FLAG_CTR_NO_DF: Disables the use of the derivation function ctr_df. For an explanation, see [NIST SP 800-90A Rev. 1].
RAND_DRBG_FLAG_HMAC: Enables use of HMAC instead of the HASH DRBG.
RAND_DRBG_FLAG_MASTER
RAND_DRBG_FLAG_PUBLIC
RAND_DRBG_FLAG_PRIVATE: These 3 flags can be used to set the individual DRBG types created. Multiple calls are required to set the types to different values. If none of these 3 flags are used, then the same type and flags are used for all 3 DRBGs in the drbg chain (<master>, <public> and <private>).

If a parent instance is specified then this will be used instead of the default entropy source for reseeding the drbg. It is said that the drbg is chained to its parent. For more information, see the NOTES section.

RAND_DRBG_instantiate() seeds the drbg instance using random input from trusted entropy sources. Optionally, a personalization string pers of length perslen can be specified. To omit the personalization string, set pers=NULL and perslen=0;

RAND_DRBG_uninstantiate() clears the internal state of the drbg and puts it back in the uninstantiated state.

RETURN VALUES

RAND_DRBG_new_ex(), RAND_DRBG_new(), RAND_DRBG_secure_new_ex() and RAND_DRBG_secure_new() return a pointer to a DRBG instance allocated on the heap, resp. secure heap.

RAND_DRBG_set(), RAND_DRBG_instantiate(), and RAND_DRBG_uninstantiate() return 1 on success, and 0 on failure.

RAND_DRBG_free() does not return a value.

NOTES

The DRBG design supports chaining, which means that a DRBG instance can use another parent DRBG instance instead of the default entropy source to obtain fresh random input for reseeding, provided that parent DRBG instance was properly instantiated, either from a trusted entropy source, or from yet another parent DRBG instance. For a detailed description of the reseeding process, see SEE ALSO

OPENSSL_secure_zalloc(3), RAND_DRBG(7)

HISTORY

The RAND_DRBG functions were added in OpenSSL 1.1.1.

COPYRIGHT

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

OpenSSL.vip