Update copyright year

[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 27142abf19e3f1654c4282f9843a07458b200289..d8b9633c7af6ff702da19c467a7fc4b3ca83a149 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.
@@ -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,20 +147,20 @@ 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-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