=pod

=head1 NAME

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

=head1 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);

 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);
 int RAND_DRBG_verify_zeroization(RAND_DRBG *drbg);

Deprecated since OpenSSL 3.0, can be hidden entirely by defining
B<OPENSSL_API_COMPAT> with a suitable version value, see
L<openssl_user_macros(7)>:

 int RAND_DRBG_set(RAND_DRBG *drbg,
                   int type, unsigned int flags);

=head1 DESCRIPTION

RAND_DRBG_new_ex() creates a new DRBG instance of the given B<type> for the
given OPENSSL_CTX <ctx>.
The <ctx> parameter can be NULL in which case the default OPENSSL_CTX is used.
RAND_DRBG_new() is the same as RAND_DRBG_new_ex() except that the default
OPENSSL_CTX is always used.

RAND_DRBG_set() initializes the B<drbg> with the given B<type> and B<flags>.
This function is deprecated.  Applications should instead use
RAND_DRBG_new_ex() to create a new DRBG.

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

The DRBG types are AES-CTR, HMAC and HASH so B<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 B<flags> argument specifies a set of bit flags which can be
joined using the | operator. The supported flags are:

=over 4

=item 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].

=item RAND_DRBG_FLAG_HMAC

Enables use of HMAC instead of the HASH DRBG.

=item RAND_DRBG_FLAG_PRIMARY

=item RAND_DRBG_FLAG_PUBLIC

=item 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
B<drbg> chain (<master>, <public> and <private>).

=back

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

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

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

RAND_DRBG_verify_zeroization() confirms if the internal DRBG state is
currently zeroed.

=head1 RETURN VALUES


RAND_DRBG_new_ex() and RAND_DRBG_new() return a pointer to a DRBG instance
allocated on the heap.

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

RAND_DRBG_verify_zeroization() returns 1 if the DRBG state is current zeroed,
and 0 if not.

RAND_DRBG_free() does not return a value.

=head1 NOTES

The DRBG design supports I<chaining>, which means that a DRBG instance can
use another B<parent> DRBG instance instead of the default entropy source
to obtain fresh random input for reseeding, provided that B<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 L<RAND_DRBG(7)>.

The default DRBG type and flags are applied only during creation of a DRBG
instance.
To ensure that they are applied to the global and thread-local DRBG instances
(<master>, resp. <public> and <private>), it is necessary to call
RAND_DRBG_set_defaults() before creating any thread and before calling any
cryptographic routines that obtain random data directly or indirectly.

=head1 SEE ALSO

L<RAND_DRBG_generate(3)>,
L<RAND_DRBG(7)>

=head1 HISTORY

The RAND_DRBG_set() function was deprecated in OpenSSL 3.0.

The RAND_DRBG functions were added in OpenSSL 1.1.1.

=head1 COPYRIGHT

Copyright 2017-2020 The OpenSSL Project Authors. All Rights Reserved.

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
L<https://www.openssl.org/source/license.html>.

=cut