doc: document digest and cipher dup functions

Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/17529)

2 files changed, 35 insertions, 2 deletions

diff --git a/doc/man3/EVP_DigestInit.pod b/doc/man3/EVP_DigestInit.pod
index 5b9d75b704..2a2a17f27f 100644
--- a/doc/man3/EVP_DigestInit.pod
+++ b/doc/man3/EVP_DigestInit.pod
@@ -4,8 +4,8 @@
 
 EVP_MD_fetch, EVP_MD_up_ref, EVP_MD_free,
 EVP_MD_get_params, EVP_MD_gettable_params,
-EVP_MD_CTX_new, EVP_MD_CTX_reset, EVP_MD_CTX_free, EVP_MD_CTX_copy,
-EVP_MD_CTX_copy_ex, EVP_MD_CTX_ctrl,
+EVP_MD_CTX_new, EVP_MD_CTX_reset, EVP_MD_CTX_free, EVP_MD_CTX_dup,
+EVP_MD_CTX_copy, EVP_MD_CTX_copy_ex, EVP_MD_CTX_ctrl,
 EVP_MD_CTX_set_params, EVP_MD_CTX_get_params,
 EVP_MD_settable_ctx_params, EVP_MD_gettable_ctx_params,
 EVP_MD_CTX_settable_params, EVP_MD_CTX_gettable_params,
@@ -63,6 +63,7 @@ EVP_MD_CTX_type, EVP_MD_CTX_pkey_ctx, EVP_MD_CTX_md_data
  int EVP_DigestFinal_ex(EVP_MD_CTX *ctx, unsigned char *md, unsigned int *s);
  int EVP_DigestFinalXOF(EVP_MD_CTX *ctx, unsigned char *md, size_t len);
 
+ EVP_MD_CTX *EVP_MD_CTX_dup(const EVP_MD_CTX *in);
  int EVP_MD_CTX_copy_ex(EVP_MD_CTX *out, const EVP_MD_CTX *in);
 
  int EVP_DigestInit(EVP_MD_CTX *ctx, const EVP_MD *type);
@@ -295,6 +296,12 @@ It retrieves the digest value from I<ctx> and places it in I<len>-sized I<md>.
 After calling this function no additional calls to EVP_DigestUpdate() can be
 made, but EVP_DigestInit_ex2() can be called to initialize a new operation.
 
+=item EVP_MD_CTX_dup()
+
+Can be used to duplicate the message digest state from I<in>.  This is useful
+to avoid multiple EVP_MD_fetch() calls or if large amounts of data are to be
+hashed which only differ in the last few bytes.
+
 =item EVP_MD_CTX_copy_ex()
 
 Can be used to copy the message digest state from I<in> to I<out>. This is
@@ -592,6 +599,10 @@ EVP_MD_CTX_gettable_params()
 Return an array of constant B<OSSL_PARAM>s, or NULL if there is none
 to get.
 
+=item EVP_MD_CTX_dup()
+
+Returns a new EVP_MD_CTX if successful or NULL on failure.
+
 =item EVP_MD_CTX_copy_ex()
 
 Returns 1 if successful or 0 for failure.
@@ -761,6 +772,8 @@ EVP_MD_CTX_get0_md() instead.
 EVP_MD_CTX_update_fn() and EVP_MD_CTX_set_update_fn() were deprecated
 in OpenSSL 3.0.
 
+EVP_MD_CTX_dup() was added in OpenSSL 3.1.
+
 =head1 COPYRIGHT
 
 Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.
diff --git a/doc/man3/EVP_EncryptInit.pod b/doc/man3/EVP_EncryptInit.pod
index fcaa5d669d..b220e6e0b8 100644
--- a/doc/man3/EVP_EncryptInit.pod
+++ b/doc/man3/EVP_EncryptInit.pod
@@ -8,6 +8,8 @@ EVP_CIPHER_free,
 EVP_CIPHER_CTX_new,
 EVP_CIPHER_CTX_reset,
 EVP_CIPHER_CTX_free,
+EVP_CIPHER_CTX_dup,
+EVP_CIPHER_CTX_copy,
 EVP_EncryptInit_ex,
 EVP_EncryptInit_ex2,
 EVP_EncryptUpdate,
@@ -109,6 +111,8 @@ EVP_CIPHER_CTX_mode
  EVP_CIPHER_CTX *EVP_CIPHER_CTX_new(void);
  int EVP_CIPHER_CTX_reset(EVP_CIPHER_CTX *ctx);
  void EVP_CIPHER_CTX_free(EVP_CIPHER_CTX *ctx);
+ EVP_CIPHER_CTX *EVP_CIPHER_CTX_dup(const EVP_CIPHER_CTX *in);
+ int EVP_CIPHER_CTX_copy(EVP_CIPHER_CTX *out, const EVP_CIPHER_CTX *in);
 
  int EVP_EncryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
                         ENGINE *impl, const unsigned char *key, const unsigned char *iv);
@@ -280,6 +284,16 @@ associated with it, including I<ctx> itself. This function should be called afte
 all operations using a cipher are complete so sensitive information does not
 remain in memory.
 
+=item EVP_CIPHER_CTX_dup()
+
+Can be used to duplicate the cipher state from I<in>.  This is useful
+to avoid multiple EVP_MD_fetch() calls or if large amounts of data are to be
+hashed which only differ in the last few bytes.
+
+=item EVP_CIPHER_CTX_copy()
+
+Can be used to copy the cipher state from I<in> to I<out>.
+
 =item EVP_CIPHER_CTX_ctrl()
 
 I<This is a legacy method.> EVP_CIPHER_CTX_set_params() and
@@ -1186,6 +1200,10 @@ EVP_CIPHER_up_ref() returns 1 for success or 0 otherwise.
 EVP_CIPHER_CTX_new() returns a pointer to a newly created
 B<EVP_CIPHER_CTX> for success and B<NULL> for failure.
 
+EVP_CIPHER_CTX_dup() returns a new EVP_MD_CTX if successful or NULL on failure.
+
+EVP_CIPHER_CTX_copy() returns 1 if successful or 0 for failure.
+
 EVP_EncryptInit_ex2(), EVP_EncryptUpdate() and EVP_EncryptFinal_ex()
 return 1 for success and 0 for failure.
 
@@ -1699,6 +1717,8 @@ non-deprecated alias macro.
 
 The EVP_CIPHER_CTX_flags() macro was deprecated in OpenSSL 1.1.0.
 
+EVP_CIPHER_CTX_dup() was added in OpenSSL 3.1.
+
 =head1 COPYRIGHT
 
 Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.