=head1 NAME
+RAND_DRBG_new_ex,
RAND_DRBG_new,
+RAND_DRBG_secure_new_ex,
RAND_DRBG_secure_new,
RAND_DRBG_set,
RAND_DRBG_set_defaults,
#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,
void RAND_DRBG_free(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() and RAND_DRBG_secure_new()
-create a new DRBG instance of the given B<type>, allocated from the heap resp.
-the secure heap
-(using OPENSSL_zalloc() resp. OPENSSL_secure_zalloc()).
+RAND_DRBG_new_ex() and RAND_DRBG_secure_new_ex() create 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() 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.
+As of OpenSSL 3.0, there is no different between the new and secure_new
+functions.
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.
-Currently, all DRBG types are based on AES-CTR, so B<type> can be one of the
-following values: NID_aes_128_ctr, NID_aes_192_ctr, NID_aes_256_ctr.
+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. Currently, the only flag is
-RAND_DRBG_FLAG_CTR_NO_DF, which disables the use of a the derivation function
-ctr_df. For an explanation, see [NIST SP 800-90A Rev. 1].
+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_MASTER
+
+=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
=head1 RETURN VALUES
-RAND_DRBG_new() and RAND_DRBG_secure_new() return a pointer to a DRBG
-instance allocated on the heap, resp. secure heap.
+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.
RAND_DRBG_set(),
RAND_DRBG_instantiate(), and
RAND_DRBG_set_defaults() before creating any thread and before calling any
cryptographic routines that obtain random data directly or indirectly.
-=head1 HISTORY
-
-The RAND_DRBG functions were added in OpenSSL 1.1.1.
+As of OpenSSL 3.0, RAND_DRBG_new() and RAND_DRBG_secure_new() are
+functionally identical. The DRBG is allocated on the normal heap and its
+sensitive state is allocated on the secure heap. Likewise for,
+RAND_DRBG_new_ex() and RAND_DRBG_secure_new_ex().
=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-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2017-2019 The OpenSSL Project Authors. All Rights Reserved.
-Licensed under the OpenSSL license (the "License"). You may not use
+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>.
projects / openssl.git / blobdiff