Document the functions EVP_MD_fetch() and EVP_MD_upref()

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

diff --git a/doc/man3/EVP_MD_meth_new.pod b/doc/man3/EVP_MD_meth_new.pod
index c15a31e7fcb074082f7857bbf0f72e8ebc077ed1..6269a05c3462fcb195fae8237696ab216336a3c9 100644 (file)
--- a/doc/man3/EVP_MD_meth_new.pod
+++ b/doc/man3/EVP_MD_meth_new.pod
@@ -11,7 +11,7 @@ EVP_MD_meth_set_ctrl, EVP_MD_meth_get_input_blocksize,
 EVP_MD_meth_get_result_size, EVP_MD_meth_get_app_datasize,
 EVP_MD_meth_get_flags, EVP_MD_meth_get_init, EVP_MD_meth_get_update,
 EVP_MD_meth_get_final, EVP_MD_meth_get_copy, EVP_MD_meth_get_cleanup,
-EVP_MD_meth_get_ctrl, EVP_MD_CTX_md_data
+EVP_MD_meth_get_ctrl, EVP_MD_upref
 - Routines to build up EVP_MD methods
 
 =head1 SYNOPSIS
@@ -34,7 +34,6 @@ EVP_MD_meth_get_ctrl, EVP_MD_CTX_md_data
                                                     unsigned char *md));
  int EVP_MD_meth_set_copy(EVP_MD *md, int (*copy)(EVP_MD_CTX *to,
                                                   const EVP_MD_CTX *from));
- void *EVP_MD_CTX_md_data(const EVP_MD_CTX *ctx);
  int EVP_MD_meth_set_cleanup(EVP_MD *md, int (*cleanup)(EVP_MD_CTX *ctx));
  int EVP_MD_meth_set_ctrl(EVP_MD *md, int (*ctrl)(EVP_MD_CTX *ctx, int cmd,
                                                   int p1, void *p2));
@@ -55,17 +54,21 @@ EVP_MD_meth_get_ctrl, EVP_MD_CTX_md_data
  int (*EVP_MD_meth_get_ctrl(const EVP_MD *md))(EVP_MD_CTX *ctx, int cmd,
                                                int p1, void *p2);
 
+ int EVP_MD_upref(EVP_MD *md);
+
 =head1 DESCRIPTION
 
 The B<EVP_MD> type is a structure for digest method implementation.
 It can also have associated public/private key signing and verifying
 routines.
 
-EVP_MD_meth_new() creates a new B<EVP_MD> structure.
+EVP_MD_meth_new() creates a new B<EVP_MD> structure. Note that B<EVP_MD>
+structures are reference counted.
 
 EVP_MD_meth_dup() creates a copy of B<md>.
 
-EVP_MD_meth_free() destroys a B<EVP_MD> structure.
+EVP_MD_meth_free() decrements the reference count for the B<EVP_MD> structure.
+If the reference count drops to 0 then the structure is freed.
 
 EVP_MD_meth_set_input_blocksize() sets the internal input block size
 for the method B<md> to B<blocksize> bytes.
@@ -85,7 +88,12 @@ together.  The available flags are:
 
 =item EVP_MD_FLAG_ONESHOT
 
-This digest method can only handles one block of input.
+This digest method can only handle one block of input.
+
+=item EVP_MD_FLAG_XOF
+
+This digest method is an extensible-output function (XOF) and supports
+the B<EVP_MD_CTRL_XOF_LEN> control.
 
 =item EVP_MD_FLAG_DIGALGID_NULL
 
@@ -106,19 +114,24 @@ B<EVP_MD_FLAG_DIGALGID_ABSENT> as default.  I<Note: if combined with
 EVP_MD_FLAG_DIGALGID_NULL, the latter will be overridden.>
 Currently unused.
 
+=item EVP_MD_FLAG_FIPS
+
+This digest method is suitable for use in FIPS mode.
+Currently unused.
+
 =back
 
 EVP_MD_meth_set_init() sets the digest init function for B<md>.
-The digest init function is called by EVP_DigestInit(),
+The digest init function is called by EVP_Digest(), EVP_DigestInit(),
 EVP_DigestInit_ex(), EVP_SignInit, EVP_SignInit_ex(), EVP_VerifyInit()
 and EVP_VerifyInit_ex().
 
 EVP_MD_meth_set_update() sets the digest update function for B<md>.
-The digest update function is called by EVP_DigestUpdate(),
+The digest update function is called by EVP_Digest(), EVP_DigestUpdate() and
 EVP_SignUpdate().
 
 EVP_MD_meth_set_final() sets the digest final function for B<md>.
-The digest final function is called by EVP_DigestFinal(),
+The digest final function is called by EVP_Digest(), EVP_DigestFinal(),
 EVP_DigestFinal_ex(), EVP_SignFinal() and EVP_VerifyFinal().
 
 EVP_MD_meth_set_copy() sets the function for B<md> to do extra
@@ -139,7 +152,7 @@ This cleanup function is called by EVP_MD_CTX_reset() and
 EVP_MD_CTX_free().
 
 EVP_MD_meth_set_ctrl() sets the control function for B<md>.
-
+See L<EVP_MD_CTX_ctrl(3)> for the available controls.
 
 EVP_MD_meth_get_input_blocksize(), EVP_MD_meth_get_result_size(),
 EVP_MD_meth_get_app_datasize(), EVP_MD_meth_get_flags(),
@@ -149,6 +162,21 @@ EVP_MD_meth_get_cleanup() and EVP_MD_meth_get_ctrl() are all used
 to retrieve the method data given with the EVP_MD_meth_set_*()
 functions above.
 
+EVP_MD_upref() increments the reference count for an EVP_MD structure.
+
+=head1 RETURN VALUES
+
+EVP_MD_meth_new() and EVP_MD_meth_dup() return a pointer to a newly
+created B<EVP_MD>, or NULL on failure.
+All EVP_MD_meth_set_*() functions return 1.
+EVP_MD_get_input_blocksize(), EVP_MD_meth_get_result_size(),
+EVP_MD_meth_get_app_datasize() and EVP_MD_meth_get_flags() return the
+indicated sizes or flags.
+All other EVP_CIPHER_meth_get_*() functions return pointers to their
+respective B<md> function.
+
+EVP_MD_upref() returns 1 for success or 0 otherwise.
+
 =head1 SEE ALSO
 
 L<EVP_DigestInit(3)>, L<EVP_SignInit(3)>, L<EVP_VerifyInit(3)>
@@ -156,13 +184,14 @@ L<EVP_DigestInit(3)>, L<EVP_SignInit(3)>, L<EVP_VerifyInit(3)>
 =head1 HISTORY
 
 The B<EVP_MD> structure was openly available in OpenSSL before version
-1.1.  The functions described here were added in OpenSSL version 1.1.
+1.1.  EVP_MD_upref() was added in OpenSSL 3.0. All other functions described
+here were added in OpenSSL 1.1.
 
 =head1 COPYRIGHT
 
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2015-2018 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>.