Fix typo in CONTRIBUTING.md

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

diff --git a/doc/man3/EVP_MAC.pod b/doc/man3/EVP_MAC.pod
index 0c68f42b6f4cb31792cedd476dbfd59018434522..defa4042689dc4f0d9edcd5281dd3b3ff17126b1 100644 (file)
--- a/doc/man3/EVP_MAC.pod
+++ b/doc/man3/EVP_MAC.pod
@@ -46,7 +46,7 @@ EVP_MAC_do_all_provided - EVP MAC routines
                           const char *subalg, const OSSL_PARAM *params,
                           const void *key, size_t keylen,
                           const unsigned char *data, size_t datalen,
-                          unsigned char *out, size_t outsize, unsigned int *outlen);
+                          unsigned char *out, size_t outsize, size_t *outlen);
  int EVP_MAC_init(EVP_MAC_CTX *ctx, const unsigned char *key, size_t keylen,
                   const OSSL_PARAM params[]);
  int EVP_MAC_update(EVP_MAC_CTX *ctx, const unsigned char *data, size_t datalen);
@@ -145,6 +145,9 @@ the key.  If I<key> is NULL, the key must be set via I<params> either
 as part of this call or separately using EVP_MAC_CTX_set_params().
 Providing non-NULL I<params> to this function is equivalent to calling
 EVP_MAC_CTX_set_params() with those I<params> for the same I<ctx> beforehand.
+Note: There are additional requirements for some MAC algorithms during
+re-initalization (i.e. calling EVP_MAC_init() on an EVP_MAC after EVP_MAC_final()
+has been called on the same object).  See the NOTES section below.
 
 EVP_MAC_init() should be called before EVP_MAC_update() and EVP_MAC_final().
 
@@ -181,32 +184,29 @@ EVP_MAC_CTX_set_params() passes chosen parameters to the underlying
 context, given a context I<ctx>.
 The set of parameters given with I<params> determine exactly what
 parameters are passed down.
-If I<params> are NULL, the unterlying context should do nothing and return 1.
+If I<params> are NULL, the underlying context should do nothing and return 1.
 Note that a parameter that is unknown in the underlying context is
 simply ignored.
 Also, what happens when a needed parameter isn't passed down is
 defined by the implementation.
 
-EVP_MAC_gettable_params() returns an B<OSSL_PARAM> array that describes
+EVP_MAC_gettable_params() returns an L<OSSL_PARAM(3)> array that describes
 the retrievable and settable parameters.  EVP_MAC_gettable_params()
 returns parameters that can be used with EVP_MAC_get_params().
-See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as a parameter descriptor.
 
 EVP_MAC_gettable_ctx_params() and EVP_MAC_CTX_gettable_params()
-return constant B<OSSL_PARAM> arrays that describe the retrievable
+return constant L<OSSL_PARAM(3)> arrays that describe the retrievable
 parameters that can be used with EVP_MAC_CTX_get_params().
 EVP_MAC_gettable_ctx_params() returns the parameters that can be retrieved
 from the algorithm, whereas EVP_MAC_CTX_gettable_params() returns
 the parameters that can be retrieved in the context's current state.
-See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as a parameter descriptor.
 
 EVP_MAC_settable_ctx_params() and EVP_MAC_CTX_settable_params() return
-constant B<OSSL_PARAM> arrays that describe the settable parameters that
+constant L<OSSL_PARAM(3)> arrays that describe the settable parameters that
 can be used with EVP_MAC_CTX_set_params().  EVP_MAC_settable_ctx_params()
 returns the parameters that can be retrieved from the algorithm,
 whereas EVP_MAC_CTX_settable_params() returns the parameters that can
-be retrieved in the context's current state.  See L<OSSL_PARAM(3)>
-for the use of B<OSSL_PARAM> as a parameter descriptor.
+be retrieved in the context's current state.
 
 =head2 Information functions
 
@@ -282,14 +282,16 @@ This option is used by KMAC.
 A simple flag to set the MAC digest to not initialise the
 implementation specific data. The value 0 or 1 is expected.
 
-This option is used by HMAC.
+This option is deprecated and will be removed in a future release.
+The option may be set, but is ignored.
 
 =item "digest-oneshot" (B<OSSL_MAC_PARAM_DIGEST_ONESHOT>) <integer>
 
 A simple flag to set the MAC digest to be a oneshot operation.
 The value 0 or 1 is expected.
 
-This option is used by HMAC.
+This option is deprecated and will be removed in a future release.
+The option may be set, but is ignored.
 
 =item "properties" (B<OSSL_MAC_PARAM_PROPERTIES>) <UTF8 string>
 
@@ -345,6 +347,13 @@ not be considered a breaking change to the API.
 The usage of the parameter names "custom", "iv" and "salt" correspond to
 the names used in the standard where the algorithm was defined.
 
+Some MAC algorithms store internal state that cannot be extracted during
+re-initalization.  For example GMAC cannot extract an B<IV> from the
+underlying CIPHER context, and so calling EVP_MAC_init() on an EVP_MAC object
+after EVP_MAC_final() has been called cannot reset its cipher state to what it
+was when the B<IV> was initially generated.  For such instances, an
+B<OSSL_MAC_PARAM_IV> parameter must be passed with each call to EVP_MAC_init().
+
 =head1 RETURN VALUES
 
 EVP_MAC_fetch() returns a pointer to a newly fetched B<EVP_MAC>, or
@@ -484,7 +493,7 @@ These functions were added in OpenSSL 3.0.
 
 =head1 COPYRIGHT
 
-Copyright 2018-2021 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2018-2024 The OpenSSL Project Authors. All Rights Reserved.
 
 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