EVP digest list: one hash algorithm per file, synchronize EVP list, o…

doc/man3/EVP_DigestInit.pod

@@ -7,10 +7,8 @@ EVP_MD_CTX_ctrl, 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_null, EVP_md2, EVP_md5, EVP_sha1,
-EVP_sha224, EVP_sha256, EVP_sha384, EVP_sha512, EVP_sha3_224, EVP_sha3_256,
-EVP_sha3_384, EVP_sha3_512, EVP_mdc2, EVP_ripemd160, EVP_blake2b512,
-EVP_blake2s256, EVP_get_digestbyname, EVP_get_digestbynid,
+EVP_MD_CTX_block_size, EVP_MD_CTX_type, EVP_md_null,
+EVP_get_digestbyname, EVP_get_digestbynid,
 EVP_get_digestbyobj - EVP digest routines
 
 =head1 SYNOPSIS
@@ -45,23 +43,6 @@ EVP_get_digestbyobj - EVP digest routines
  int EVP_MD_CTX_type(const EVP_MD *ctx);
 
  const EVP_MD *EVP_md_null(void);
- const EVP_MD *EVP_md2(void);
- const EVP_MD *EVP_md5(void);
- const EVP_MD *EVP_sha1(void);
- const EVP_MD *EVP_mdc2(void);
- const EVP_MD *EVP_ripemd160(void);
- const EVP_MD *EVP_blake2b512(void);
- const EVP_MD *EVP_blake2s256(void);
-
- const EVP_MD *EVP_sha224(void);
- const EVP_MD *EVP_sha256(void);
- const EVP_MD *EVP_sha384(void);
- const EVP_MD *EVP_sha512(void);
-
- const EVP_MD *EVP_sha3_224(void);
- const EVP_MD *EVP_sha3_256(void);
- const EVP_MD *EVP_sha3_384(void);
- const EVP_MD *EVP_sha3_512(void);
 
  const EVP_MD *EVP_get_digestbyname(const char *name);
  const EVP_MD *EVP_get_digestbynid(int type);
@@ -72,120 +53,174 @@ EVP_get_digestbyobj - EVP digest routines
 The EVP digest routines are a high level interface to message digests,
 and should be used instead of the cipher-specific functions.
 
-EVP_MD_CTX_new() allocates, initializes and returns a digest context.
+=over 4
 
-EVP_MD_CTX_reset() resets the digest context B<ctx>.  This can be used
-to reuse an already existing context.
+=item EVP_MD_CTX_new()
 
-EVP_MD_CTX_free() cleans up digest context B<ctx> and frees up the
-space allocated to it.
+Allocates, initializes and returns a digest context.
 
-EVP_MD_CTX_ctrl() performs digest-specific control actions on context B<ctx>.
+=item EVP_MD_CTX_reset()
 
-EVP_DigestInit_ex() sets up digest context B<ctx> to use a digest
-B<type> from ENGINE B<impl>. B<ctx> must be initialized before calling this
-function. B<type> will typically be supplied by a function such as EVP_sha1().
-If B<impl> is NULL then the default implementation of digest B<type> is used.
+Resets the digest context B<ctx>.  This can be used to reuse an already
+existing context.
 
-EVP_DigestUpdate() hashes B<cnt> bytes of data at B<d> into the
-digest context B<ctx>. This function can be called several times on the
-same B<ctx> to hash additional data.
+=item EVP_MD_CTX_free()
 
-EVP_DigestFinal_ex() retrieves the digest value from B<ctx> and places
-it in B<md>. If the B<s> parameter is not NULL then the number of
-bytes of data written (i.e. the length of the digest) will be written
-to the integer at B<s>, at most B<EVP_MAX_MD_SIZE> bytes will be written.
-After calling EVP_DigestFinal_ex() no additional calls to EVP_DigestUpdate()
-can be made, but EVP_DigestInit_ex() can be called to initialize a new
-digest operation.
+Cleans up digest context B<ctx> and frees up the space allocated to it.
 
-EVP_DigestFinalXOF() interfaces to extendable-output functions, XOFs,
-such as SHAKE128 and SHAKE256. It retrieves the digest value from
-B<ctx> and places it in B<len>-sized <B>md. After calling this function
+=item EVP_MD_CTX_ctrl()
+
+Performs digest-specific control actions on context B<ctx>.
+
+=item EVP_DigestInit_ex()
+
+Sets up digest context B<ctx> to use a digest B<type> from ENGINE B<impl>.
+B<ctx> must be initialized before calling this function. B<type> will typically
+be supplied by a function such as EVP_sha1().  If B<impl> is NULL then the
+default implementation of digest B<type> is used.
+
+=item EVP_DigestUpdate()
+
+Hashes B<cnt> bytes of data at B<d> into the digest context B<ctx>. This
+function can be called several times on the same B<ctx> to hash additional
+data.
+
+=item EVP_DigestFinal_ex()
+
+Retrieves the digest value from B<ctx> and places it in B<md>. If the B<s>
+parameter is not NULL then the number of bytes of data written (i.e. the
+length of the digest) will be written to the integer at B<s>, at most
+B<EVP_MAX_MD_SIZE> bytes will be written.  After calling EVP_DigestFinal_ex()
 no additional calls to EVP_DigestUpdate() can be made, but
-EVP_DigestInit_ex() can be called to initialize a new operation.
+EVP_DigestInit_ex() can be called to initialize a new digest operation.
+
+=item EVP_DigestFinalXOF()
+
+Interfaces to extendable-output functions, XOFs, such as SHAKE128 and SHAKE256.
+It retrieves the digest value from B<ctx> and places it in B<len>-sized <B>md.
+After calling this function no additional calls to EVP_DigestUpdate() can be
+made, but EVP_DigestInit_ex() can be called to initialize a new operation.
+
+=item EVP_MD_CTX_copy_ex()
+
+Can be used to copy the message digest state from B<in> to B<out>. This is
+useful if large amounts of data are to be hashed which only differ in the last
+few bytes. B<out> must be initialized before calling this function.
+
+=item EVP_DigestInit()
+
+Behaves in the same way as EVP_DigestInit_ex() except the passed context B<ctx>
+does not have to be initialized, and it always uses the default digest
+implementation.
+
+=item EVP_DigestFinal()
+
+Similar to EVP_DigestFinal_ex() except the digest context B<ctx> is
+automatically cleaned up.
+
+=item EVP_MD_CTX_copy()
 
-EVP_MD_CTX_copy_ex() can be used to copy the message digest state from
-B<in> to B<out>. This is useful if large amounts of data are to be
-hashed which only differ in the last few bytes. B<out> must be initialized
-before calling this function.
+Similar to EVP_MD_CTX_copy_ex() except the destination B<out> does not have to
+be initialized.
 
-EVP_DigestInit() behaves in the same way as EVP_DigestInit_ex() except
-the passed context B<ctx> does not have to be initialized, and it always
-uses the default digest implementation.
+=item EVP_MD_size(),
+EVP_MD_CTX_size()
 
-EVP_DigestFinal() is similar to EVP_DigestFinal_ex() except the digest
-context B<ctx> is automatically cleaned up.
+Return the size of the message digest when passed an B<EVP_MD> or an
+B<EVP_MD_CTX> structure, i.e. the size of the hash.
 
-EVP_MD_CTX_copy() is similar to EVP_MD_CTX_copy_ex() except the destination
-B<out> does not have to be initialized.
+=item EVP_MD_block_size(),
+EVP_MD_CTX_block_size()
 
-EVP_MD_size() and EVP_MD_CTX_size() return the size of the message digest
-when passed an B<EVP_MD> or an B<EVP_MD_CTX> structure, i.e. the size of the
-hash.
+Return the block size of the message digest when passed an B<EVP_MD> or an
+B<EVP_MD_CTX> structure.
 
-EVP_MD_block_size() and EVP_MD_CTX_block_size() return the block size of the
-message digest when passed an B<EVP_MD> or an B<EVP_MD_CTX> structure.
+=item EVP_MD_type(),
+EVP_MD_CTX_type()
 
-EVP_MD_type() and EVP_MD_CTX_type() return the NID of the OBJECT IDENTIFIER
-representing the given message digest when passed an B<EVP_MD> structure.
-For example EVP_MD_type(EVP_sha1()) returns B<NID_sha1>. This function is
-normally used when setting ASN1 OIDs.
+Return the NID of the OBJECT IDENTIFIER representing the given message digest
+when passed an B<EVP_MD> structure.  For example, C<EVP_MD_type(EVP_sha1())>
+returns B<NID_sha1>. This function is normally used when setting ASN1 OIDs.
 
-EVP_MD_CTX_md() returns the B<EVP_MD> structure corresponding to the passed
-B<EVP_MD_CTX>.
+=item EVP_MD_CTX_md()
 
-EVP_MD_pkey_type() returns the NID of the public key signing algorithm associated
-with this digest. For example EVP_sha1() is associated with RSA so this will
-return B<NID_sha1WithRSAEncryption>. Since digests and signature algorithms
-are no longer linked this function is only retained for compatibility
-reasons.
+Returns the B<EVP_MD> structure corresponding to the passed B<EVP_MD_CTX>.
 
-EVP_md2(), EVP_md5(), EVP_sha1(), EVP_sha224(), EVP_sha256(),
-EVP_sha384(), EVP_sha512(), EVP_sha3_224(), EVP_sha3_256(),
-EVP_sha3_384(), EVP_sha3_512(), EVP_mdc2(), EVP_ripemd160(),
-EVP_blake2b512(), and EVP_blake2s256() return B<EVP_MD> structures for
-the MD2, MD5, SHA1, SHA224, SHA256, SHA384, SHA512, SHA3-224, SHA3-256,
-SHA3-384, SHA3-512, MDC2, RIPEMD160, BLAKE2b-512, and BLAKE2s-256 digest
-algorithms respectively.
+=item EVP_MD_pkey_type()
 
-EVP_md_null() is a "null" message digest that does nothing: i.e. the hash it
-returns is of zero length.
+Returns the NID of the public key signing algorithm associated with this
+digest. For example EVP_sha1() is associated with RSA so this will return
+B<NID_sha1WithRSAEncryption>. Since digests and signature algorithms are no
+longer linked this function is only retained for compatibility reasons.
 
-EVP_get_digestbyname(), EVP_get_digestbynid() and EVP_get_digestbyobj()
-return an B<EVP_MD> structure when passed a digest name, a digest NID or
-an ASN1_OBJECT structure respectively.
+=item EVP_md_null()
+
+A "null" message digest that does nothing: i.e. the hash it returns is of zero
+length.
+
+=item EVP_get_digestbyname(),
+EVP_get_digestbynid(),
+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.
+
+=back
 
 =head1 RETURN VALUES
 
-EVP_DigestInit_ex(), EVP_DigestUpdate() and EVP_DigestFinal_ex() return 1 for
+=over 4
+
+=item EVP_DigestInit_ex(),
+EVP_DigestUpdate(),
+EVP_DigestFinal_ex()
+
+Returns 1 for
 success and 0 for failure.
 
-EVP_MD_CTX_ctrl() returns 1 if successful or 0 for failure.
+=item EVP_MD_CTX_ctrl()
+
+Returns 1 if successful or 0 for failure.
+
+=item EVP_MD_CTX_copy_ex()
 
-EVP_MD_CTX_copy_ex() returns 1 if successful or 0 for failure.
+Returns 1 if successful or 0 for failure.
 
-EVP_MD_type(), EVP_MD_pkey_type() and EVP_MD_type() return the NID of the
-corresponding OBJECT IDENTIFIER or NID_undef if none exists.
+=item EVP_MD_type(),
+EVP_MD_pkey_type(),
+EVP_MD_type()
 
-EVP_MD_size(), EVP_MD_block_size(), EVP_MD_CTX_size() and
-EVP_MD_CTX_block_size() return the digest or block size in bytes.
+Returns the NID of the corresponding OBJECT IDENTIFIER or NID_undef if none
+exists.
 
-EVP_md_null(), EVP_md2(), EVP_md5(), EVP_sha1(),
-EVP_mdc2(), EVP_ripemd160(), EVP_blake2b512(), and EVP_blake2s256() return
-pointers to the corresponding EVP_MD structures.
+=item EVP_MD_size(),
+EVP_MD_block_size(),
+EVP_MD_CTX_size(),
+EVP_MD_CTX_block_size()
 
-EVP_get_digestbyname(), EVP_get_digestbynid() and EVP_get_digestbyobj()
-return either an B<EVP_MD> structure or NULL if an error occurs.
+Returns the digest or block size in bytes.
+
+=item EVP_md_null()
+
+Returns a pointer to the B<EVP_MD> structure of the "null" message digest.
+
+=item EVP_get_digestbyname(),
+EVP_get_digestbynid(),
+EVP_get_digestbyobj()
+
+Returns either an B<EVP_MD> structure or NULL if an error occurs.
+
+=back
 
 =head1 NOTES
 
 The B<EVP> interface to message digests should almost always be used in
 preference to the low level interfaces. This is because the code then becomes
 transparent to the digest used and much more flexible.
 
-New applications should use the SHA2 digest algorithms such as SHA256.
-The other digest algorithms are still in common use.
+New applications should use the SHA-2 (such as L<EVP_sha256(3)>) or the SHA-3
+digest algorithms (such as L<EVP_sha3_512>). The other digest algorithms are
+still in common use.
 
 For most applications the B<impl> parameter to EVP_DigestInit_ex() will be
 set to NULL to use the default digest implementation.
@@ -255,6 +290,19 @@ digest name passed on the command line.
 L<dgst(1)>,
 L<evp(7)>
 
+The full list of digest algorithms are provided below.
+
+L<EVP_blake2b512(3)>,
+L<EVP_md2(3)>,
+L<EVP_md4(3)>,
+L<EVP_md5(3)>,
+L<EVP_mdc2(3)>,
+L<EVP_ripemd160(3)>,
+L<EVP_sha1(3)>,
+L<EVP_sha224(3)>,
+L<EVP_sha3_224(3)>,
+L<EVP_whirlpool(3)>
+
 =head1 HISTORY
 
 EVP_MD_CTX_create() and EVP_MD_CTX_destroy() were renamed to
@@ -263,7 +311,7 @@ EVP_MD_CTX_new() and EVP_MD_CTX_free() in OpenSSL 1.1.0.
 The link between digests and signing algorithms was fixed in OpenSSL 1.0 and
 later, so now EVP_sha1() can be used with RSA and DSA.
 
-EVP_dss1() was removed in OpenSSL 1.1.0
+EVP_dss1() was removed in OpenSSL 1.1.0.
 
 =head1 COPYRIGHT
 

doc/man3/EVP_blake2b512.pod

@@ -0,0 +1,65 @@
+=pod
+
+=head1 NAME
+
+EVP_blake2b512,
+EVP_blake2s256
+- BLAKE2 For EVP
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ const EVP_MD *EVP_blake2b512(void);
+ const EVP_MD *EVP_blake2s256(void);
+
+=head1 DESCRIPTION
+
+BLAKE2 is an improved version of BLAKE, which was submitted to the NIST SHA-3
+algorithm competition. The BLAKE2s and BLAKE2b algorithms are described in
+RFC 7693.
+
+=over 4
+
+=item EVP_blake2s256()
+
+The BLAKE2s algorithm that produces a 256-bit output from a given input.
+
+=item EVP_blake2b512()
+
+The BLAKE2b algorithm that produces a 512-bit output from a given input.
+
+=back
+
+=head1 RETURN VALUES
+
+These functions return a B<EVP_MD> structure that contains the
+implementation of the symmetric cipher. See L<EVP_MD_meth_new(3)> for
+details of the B<EVP_MD> structure.
+
+=head1 CONFORMING TO
+
+RFC 7693.
+
+=head1 NOTES
+
+While the BLAKE2b and BLAKE2s algorithms supports a variable length digest,
+this implementation outputs a digest of a fixed length (the maximum length
+supported), which is 512-bits for BLAKE2b and 256-bits for BLAKE2s.
+
+=head1 SEE ALSO
+
+L<evp(7)>,
+L<EVP_DigestInit(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2017 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
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
+