Add missing EVP_MD documentation

Signed-off-by: Antoine Salon <asalon@vmware.com>
Reviewed-by: Paul Dale <paul.dale@oracle.com>
Reviewed-by: Matt Caswell <matt@openssl.org>
(cherry picked from commit 37842dfaebcf28b4ca452c6abd93ebde1b4aa6dc)

Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
(Merged from https://github.com/openssl/openssl/pull/10094)

diff --git a/doc/man3/EVP_DigestInit.pod b/doc/man3/EVP_DigestInit.pod
index d5cbee45ca774b8cfbf48daeac7396f5c1c7b2bc..434e22030fdd3e9112a50a4f771ad1f519e811a5 100644 (file)
--- a/doc/man3/EVP_DigestInit.pod
+++ b/doc/man3/EVP_DigestInit.pod
@@ -2,17 +2,17 @@
 
 =head1 NAME
 
-EVP_MD_CTX_new, EVP_MD_CTX_reset, EVP_MD_CTX_free, EVP_MD_CTX_copy_ex,
-EVP_MD_CTX_ctrl, EVP_MD_CTX_set_flags, EVP_MD_CTX_clear_flags,
-EVP_MD_CTX_test_flags, EVP_DigestInit_ex, EVP_DigestInit, EVP_DigestUpdate,
+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_set_flags,
+EVP_MD_CTX_clear_flags, EVP_MD_CTX_test_flags,
+EVP_Digest, EVP_DigestInit_ex, EVP_DigestInit, EVP_DigestUpdate,
 EVP_DigestFinal_ex, EVP_DigestFinalXOF, EVP_DigestFinal,
-EVP_MD_CTX_copy, EVP_MD_type, EVP_MD_pkey_type, EVP_MD_size,
-EVP_MD_block_size, EVP_MD_CTX_md, EVP_MD_CTX_size,
-EVP_MD_CTX_block_size, EVP_MD_CTX_type, EVP_MD_CTX_md_data,
+EVP_MD_type, EVP_MD_pkey_type, EVP_MD_size, EVP_MD_block_size, EVP_MD_flags,
+EVP_MD_CTX_md, EVP_MD_CTX_type, EVP_MD_CTX_size, EVP_MD_CTX_block_size,
+EVP_MD_CTX_md_data, EVP_MD_CTX_update_fn, EVP_MD_CTX_set_update_fn,
 EVP_md_null,
-EVP_get_digestbyname, EVP_get_digestbynid,
-EVP_get_digestbyobj,
-EVP_MD_CTX_set_pkey_ctx - EVP digest routines
+EVP_get_digestbyname, EVP_get_digestbynid, EVP_get_digestbyobj,
+EVP_MD_CTX_pkey_ctx, EVP_MD_CTX_set_pkey_ctx - EVP digest routines
 
 =head1 SYNOPSIS
 
@@ -26,6 +26,8 @@ EVP_MD_CTX_set_pkey_ctx - EVP digest routines
  void EVP_MD_CTX_clear_flags(EVP_MD_CTX *ctx, int flags);
  int EVP_MD_CTX_test_flags(const EVP_MD_CTX *ctx, int flags);
 
+ int EVP_Digest(const void *data, size_t count, unsigned char *md,
+                unsigned int *size, const EVP_MD *type, ENGINE *impl);
  int EVP_DigestInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl);
  int EVP_DigestUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt);
  int EVP_DigestFinal_ex(EVP_MD_CTX *ctx, unsigned char *md, unsigned int *s);
@@ -42,12 +44,18 @@ EVP_MD_CTX_set_pkey_ctx - EVP digest routines
  int EVP_MD_pkey_type(const EVP_MD *md);
  int EVP_MD_size(const EVP_MD *md);
  int EVP_MD_block_size(const EVP_MD *md);
+ unsigned long EVP_MD_flags(const EVP_MD *md);
 
  const EVP_MD *EVP_MD_CTX_md(const EVP_MD_CTX *ctx);
  int EVP_MD_CTX_size(const EVP_MD_CTX *ctx);
  int EVP_MD_CTX_block_size(const EVP_MD_CTX *ctx);
  int EVP_MD_CTX_type(const EVP_MD_CTX *ctx);
  void *EVP_MD_CTX_md_data(const EVP_MD_CTX *ctx);
+ int (*EVP_MD_CTX_update_fn(EVP_MD_CTX *ctx))(EVP_MD_CTX *ctx,
+                                              const void *data, size_t count);
+ void EVP_MD_CTX_set_update_fn(EVP_MD_CTX *ctx,
+                               int (*update)(EVP_MD_CTX *ctx,
+                                             const void *data, size_t count));
 
  const EVP_MD *EVP_md_null(void);
 
@@ -55,6 +63,7 @@ EVP_MD_CTX_set_pkey_ctx - EVP digest routines
  const EVP_MD *EVP_get_digestbynid(int type);
  const EVP_MD *EVP_get_digestbyobj(const ASN1_OBJECT *o);
 
+ EVP_PKEY_CTX *EVP_MD_CTX_pkey_ctx(const EVP_MD_CTX *ctx);
  void EVP_MD_CTX_set_pkey_ctx(EVP_MD_CTX *ctx, EVP_PKEY_CTX *pctx);
 
 =head1 DESCRIPTION
@@ -79,12 +88,24 @@ Cleans up digest context B<ctx> and frees up the space allocated to it.
 
 =item EVP_MD_CTX_ctrl()
 
-Performs digest-specific control actions on context B<ctx>.
+Performs digest-specific control actions on context B<ctx>. The control command
+is indicated in B<cmd> and any additional arguments in B<p1> and B<p2>.
+EVP_MD_CTX_ctrl() must be called after EVP_DigestInit_ex(). Other restrictions
+may apply depending on the control type and digest implementation.
+See L</CONTROLS> below for more information.
 
 =item EVP_MD_CTX_set_flags(), EVP_MD_CTX_clear_flags(), EVP_MD_CTX_test_flags()
 
 Sets, clears and tests B<ctx> flags.  See L</FLAGS> below for more information.
 
+=item EVP_Digest()
+
+A wrapper around the Digest Init_ex, Update and Final_ex functions.
+Hashes B<count> bytes of data at B<data> using a digest B<type> from ENGINE
+B<impl>. The digest value is placed in B<md> and its length is written at B<size>
+if the pointer is not NULL. At most B<EVP_MAX_MD_SIZE> bytes will be written.
+If B<impl> is NULL the default implementation of digest B<type> is used.
+
 =item EVP_DigestInit_ex()
 
 Sets up digest context B<ctx> to use a digest B<type> from ENGINE B<impl>.
@@ -163,6 +184,21 @@ EVP_MD_meth_set_app_datasize().
 
 Returns the B<EVP_MD> structure corresponding to the passed B<EVP_MD_CTX>.
 
+=item EVP_MD_CTX_set_update_fn()
+
+Sets the update function for B<ctx> to B<update>.
+This is the function that is called by EVP_DigestUpdate. If not set, the
+update function from the B<EVP_MD> type specified at initialization is used.
+
+=item EVP_MD_CTX_update_fn()
+
+Returns the update function for B<ctx>.
+
+=item EVP_MD_flags()
+
+Returns the B<md> flags. Note that these are different from the B<EVP_MD_CTX>
+ones. See L<EVP_MD_meth_set_flags(3)> for more information.
+
 =item EVP_MD_pkey_type()
 
 Returns the NID of the public key signing algorithm associated with this
@@ -182,10 +218,15 @@ EVP_get_digestbyobj()
 Returns an B<EVP_MD> structure when passed a digest name, a digest B<NID> or an
 B<ASN1_OBJECT> structure respectively.
 
+=item EVP_MD_CTX_pkey_ctx()
+
+Returns the B<EVP_PKEY_CTX> assigned to B<ctx>. The returned pointer should not
+be freed by the caller.
+
 =item EVP_MD_CTX_set_pkey_ctx()
 
 Assigns an B<EVP_PKEY_CTX> to B<EVP_MD_CTX>. This is usually used to provide
-a customzied B<EVP_PKEY_CTX> to L<EVP_DigestSignInit(3)> or
+a customized B<EVP_PKEY_CTX> to L<EVP_DigestSignInit(3)> or
 L<EVP_DigestVerifyInit(3)>. The B<pctx> passed to this function should be freed
 by the caller. A NULL B<pctx> pointer is also allowed to clear the B<EVP_PKEY_CTX>
 assigned to B<ctx>. In such case, freeing the cleared B<EVP_PKEY_CTX> or not
@@ -193,6 +234,27 @@ depends on how the B<EVP_PKEY_CTX> is created.
 
 =back
 
+=head1 CONTROLS
+
+EVP_MD_CTX_ctrl() can be used to send the following standard controls:
+
+=over 4
+
+=item EVP_MD_CTRL_MICALG
+
+Gets the digest Message Integrity Check algorithm string. This is used when
+creating S/MIME multipart/signed messages, as specified in RFC 3851.
+The string value is written to B<p2>.
+
+=item EVP_MD_CTRL_XOF_LEN
+
+This control sets the digest length for extendable output functions to B<p1>.
+Sending this control directly should not be necessary, the use of
+C<EVP_DigestFinalXOF()> is preferred.
+Currently used by SHAKE.
+
+=back
+
 =head1 FLAGS
 
 EVP_MD_CTX_set_flags(), EVP_MD_CTX_clear_flags() and EVP_MD_CTX_test_flags()
@@ -245,8 +307,7 @@ Returns 1 if successful or 0 for failure.
 Returns 1 if successful or 0 for failure.
 
 =item EVP_MD_type(),
-EVP_MD_pkey_type(),
-EVP_MD_type()
+EVP_MD_pkey_type()
 
 Returns the NID of the corresponding OBJECT IDENTIFIER or NID_undef if none
 exists.
@@ -350,6 +411,7 @@ digest name passed on the command line.
 
 =head1 SEE ALSO
 
+L<EVP_MD_meth_new(3)>,
 L<dgst(1)>,
 L<evp(7)>
 

diff --git a/doc/man3/EVP_MD_meth_new.pod b/doc/man3/EVP_MD_meth_new.pod
index 0265c7d50456eb3f65335b747563bb3d85097664..e17a4cd519abe03070ca35ea9c85505776ef28cf 100644 (file)
--- a/doc/man3/EVP_MD_meth_new.pod
+++ b/doc/man3/EVP_MD_meth_new.pod
@@ -84,7 +84,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
 
@@ -105,19 +110,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
@@ -138,6 +148,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(),
@@ -169,7 +180,7 @@ The B<EVP_MD> structure was openly available in OpenSSL before version
 
 =head1 COPYRIGHT
 
-Copyright 2015-2017 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
 this file except in compliance with the License.  You can obtain a copy