In documentation, consistently refer to OpenSSL 3.0

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

diff --git a/doc/man3/EVP_MAC.pod b/doc/man3/EVP_MAC.pod
index 473d6c9e6b06986e1c54b53016d8255c7351e4cd..2c6687945c6d1e61dd4f230c6b6ba18e341cd94d 100644 (file)
--- a/doc/man3/EVP_MAC.pod
+++ b/doc/man3/EVP_MAC.pod
@@ -3,7 +3,7 @@
 =head1 NAME
 
 EVP_MAC, EVP_MAC_CTX, EVP_MAC_CTX_new, EVP_MAC_CTX_new_id, EVP_MAC_CTX_free,
-EVP_MAC_CTX_copy, EVP_MAC_CTX_mac, EVP_MAC_size, EVP_MAC_init, EVP_MAC_update,
+EVP_MAC_CTX_dup, EVP_MAC_CTX_mac, EVP_MAC_size, EVP_MAC_init, EVP_MAC_update,
 EVP_MAC_final, EVP_MAC_ctrl, EVP_MAC_vctrl, EVP_MAC_ctrl_str,
 EVP_MAC_str2ctrl, EVP_MAC_hex2ctrl, EVP_MAC_nid, EVP_MAC_name,
 EVP_get_macbyname, EVP_get_macbynid, EVP_get_macbyobj - EVP MAC routines
@@ -18,7 +18,7 @@ EVP_get_macbyname, EVP_get_macbynid, EVP_get_macbyobj - EVP MAC routines
  EVP_MAC_CTX *EVP_MAC_CTX_new(const EVP_MAC *mac);
  EVP_MAC_CTX *EVP_MAC_CTX_new_id(int nid);
  void EVP_MAC_CTX_free(EVP_MAC_CTX *ctx);
- int EVP_MAC_CTX_copy(EVP_MAC_CTX *dest, EVP_MAC_CTX *src);
+ EVP_MAC_CTX *EVP_MAC_CTX_dup(const EVP_MAC_CTX *src);
  const EVP_MAC *EVP_MAC_CTX_mac(EVP_MAC_CTX *ctx);
  size_t EVP_MAC_size(EVP_MAC_CTX *ctx);
  int EVP_MAC_init(EVP_MAC_CTX *ctx);
@@ -72,10 +72,8 @@ EVP_MAC_CTX_free() frees the contents of the context, including an
 underlying context if there is one, as well as the context itself.
 B<NULL> is a valid parameter, for which this function is a no-op.
 
-EVP_MAC_CTX_copy() makes a deep copy of the C<src> context to the
-C<dest> context.
-The C<dest> context I<must> have been created before calling this
-function.
+EVP_MAC_CTX_dup() duplicates the C<src> context and returns a newly allocated
+context.
 
 EVP_MAC_CTX_mac() returns the B<EVP_MAC> associated with the context
 C<ctx>.
@@ -87,9 +85,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 +106,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.
@@ -169,9 +164,28 @@ 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.
@@ -186,6 +200,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 *>
@@ -212,13 +229,12 @@ implemented as a macro.
 
 =head1 RETURN VALUES
 
-EVP_MAC_CTX_new() and EVP_MAC_CTX_new_id() return a pointer to a newly
-created EVP_MAC_CTX, or NULL if allocation failed.
+EVP_MAC_CTX_new(), EVP_MAC_CTX_new_id() and EVP_MAC_CTX_dup() return a pointer
+to a newly 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(),
-and EVP_MAC_final() return 1 on success, 0 on error.
+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
 EVP_MAC_hex2ctrl() return 1 on success and 0 or a negative value on
@@ -332,16 +348,23 @@ F<./foo>)
 
 =head1 SEE ALSO
 
+L<EVP_MAC_BLAKE2(7)>,
 L<EVP_MAC_CMAC(7)>,
 L<EVP_MAC_GMAC(7)>,
 L<EVP_MAC_HMAC(7)>,
-L<EVP_MAC_SIPHASH(7)>
+L<EVP_MAC_KMAC(7)>,
+L<EVP_MAC_SIPHASH(7)>,
+L<EVP_MAC_POLY1305(7)>
+
+=head1 HISTORY
+
+These functions were added in OpenSSL 3.0.
 
 =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>.