Don't allow SHAKE128/SHAKE256 with HMAC

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

diff --git a/doc/man3/EVP_MAC.pod b/doc/man3/EVP_MAC.pod
index 2b4894005617a9b49b72f7ffaf2332c53fa52885..a55d8db259c099afde36ba441bfa63c98c68f521 100644 (file)
--- a/doc/man3/EVP_MAC.pod
+++ b/doc/man3/EVP_MAC.pod
@@ -87,9 +87,6 @@ through diverse controls.
 This should be called before calling EVP_MAC_update() and
 EVP_MAC_final().
 
-EVP_MAC_reset() resets the computation for the given context.
-This may not be supported by the MAC implementation.
-
 EVP_MAC_update() adds C<datalen> bytes from C<data> to the MAC input.
 
 EVP_MAC_final() does the final computation and stores the result in
@@ -111,7 +108,7 @@ This functions takes variable arguments, the exact expected arguments
 depend on C<cmd>.
 EVP_MAC_ctrl() can be called both before and after EVP_MAC_init(), but
 the effect will depend on what control is being use.
-See </CONTROLS> below for a description of standard controls.
+See L</CONTROLS> below for a description of standard controls.
 
 EVP_MAC_vctrl() is the variant of EVP_MAC_ctrl() that takes a
 C<va_list> argument instead of variadic arguments.
@@ -163,9 +160,34 @@ For MACs that use an underlying computation algorithm, the algorithm
 I<must> be set first, see B<EVP_MAC_CTRL_SET_ENGINE>,
 B<EVP_MAC_CTRL_SET_MD> and B<EVP_MAC_CTRL_SET_CIPHER> below.
 
+=item B<EVP_MAC_CTRL_SET_IV>
+
+This control expects two arguments: C<unsigned char *key>, C<size_t keylen>
+
+Some MAC implementations require an IV, this control sets the IV.
+
+=item B<EVP_MAC_CTRL_SET_CUSTOM>
+
+This control expects two arguments: C<unsigned char *custom>, C<size_t customlen>
+
+Some MAC implementations (KMAC, BLAKE2) accept a Customization String,
+this control sets the Customization String. The default value is "".
+
+=item B<EVP_MAC_CTRL_SET_SALT>
+
+This control expects two arguments: C<unsigned char *salt>, C<size_t saltlen>
+
+This option is used by BLAKE2 MAC.
+
+=item B<EVP_MAC_CTRL_SET_XOF>
+
+This control expects one argument: C<int xof>
+
+This option is used by KMAC.
+
 =item B<EVP_MAC_CTRL_SET_FLAGS>
 
-This control expects one arguments: C<unsigned long flags>
+This control expects one argument: C<unsigned long flags>
 
 These will set the MAC flags to the given numbers.
 Some MACs do not support this option.
@@ -180,6 +202,9 @@ For MAC implementations that use an underlying computation algorithm,
 these controls set what the algorithm should be, and the engine that
 implements the algorithm if needed.
 
+Note that not all algorithms may support all digests. HMAC does not support
+variable output length digests such as SHAKE128 or SHAKE256.
+
 B<EVP_MAC_CTRL_SET_ENGINE> takes one argument: C<ENGINE *>
 
 B<EVP_MAC_CTRL_SET_MD> takes one argument: C<EVP_MD *>
@@ -211,7 +236,7 @@ created EVP_MAC_CTX, or NULL if allocation failed.
 
 EVP_MAC_CTX_free() returns nothing at all.
 
-EVP_MAC_CTX_copy(), EVP_MAC_reset(), EVP_MAC_init(), EVP_MAC_update(),
+EVP_MAC_CTX_copy(), EVP_MAC_init(), EVP_MAC_update(),
 and EVP_MAC_final() return 1 on success, 0 on error.
 
 EVP_MAC_ctrl(), EVP_MAC_ctrl_str(), EVP_MAC_str2ctrl() and
@@ -326,13 +351,19 @@ F<./foo>)
 
 =head1 SEE ALSO
 
-L<EVP_MAC_CMAC(7)>
+L<EVP_MAC_BLAKE2(7)>,
+L<EVP_MAC_CMAC(7)>,
+L<EVP_MAC_GMAC(7)>,
+L<EVP_MAC_HMAC(7)>,
+L<EVP_MAC_KMAC(7)>,
+L<EVP_MAC_SIPHASH(7)>,
+L<EVP_MAC_POLY1305(7)>
 
 =head1 COPYRIGHT
 
 Copyright 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>.