evp_rand: documentation

[openssl.git] / doc / man3 / RAND_DRBG_new.pod

diff --git a/doc/man3/RAND_DRBG_new.pod b/doc/man3/RAND_DRBG_new.pod
index 125e60d6c8a6acac5a182cbc9ae2ff0ce4d32b90..7d7cdbad4487f3fd356414c5df20bd304b2d533f 100644 (file)
--- a/doc/man3/RAND_DRBG_new.pod
+++ b/doc/man3/RAND_DRBG_new.pod
@@ -2,31 +2,29 @@
 
 =head1 NAME
 
+RAND_DRBG_new_ex,
 RAND_DRBG_new,
-RAND_DRBG_secure_new,
 RAND_DRBG_set,
 RAND_DRBG_set_defaults,
 RAND_DRBG_instantiate,
 RAND_DRBG_uninstantiate,
-RAND_DRBG_free
+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);
 
- 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,
@@ -35,16 +33,26 @@ RAND_DRBG_free
  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() 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() 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.
@@ -56,7 +64,8 @@ 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 RAND_DRBG_TYPE.
+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.
@@ -83,9 +92,8 @@ Enables use of HMAC instead of the HASH DRBG.
 
 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 DRBG's in the
-B<drbg> chain (<master>, <public> and <private>). The default used if this
-method is not called is to use RAND_DRBG_FLAGS.
+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
 
@@ -94,7 +102,6 @@ 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
@@ -105,17 +112,23 @@ 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() and RAND_DRBG_secure_new() return a pointer to a DRBG
-instance allocated on the heap, resp. secure heap.
+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
@@ -134,22 +147,22 @@ To ensure that they are applied to the global and thread-local DRBG instances
 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.
-
 =head1 SEE ALSO
 
-L<OPENSSL_zalloc(3)>,
-L<OPENSSL_secure_zalloc(3)>,
 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>.