Skip to content

Commit

Permalink
Update Docs for EVP_MAC
Browse files Browse the repository at this point in the history
For GMAC/CMAC, its not possible to re-init the algorithm without
explicitly passing an OSSL_MAC_PARAM_IV to each init call, as it is
not possible to extract the IV value from the prior init call (be it
explicitly passed or auto generated).  As such, document the fact that
re-initalization requires passing an IV parameter

Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from #23235)
  • Loading branch information
nhorman authored and t8m committed Jan 11, 2024
1 parent 493ad48 commit 7c1d533
Showing 1 changed file with 10 additions and 0 deletions.
10 changes: 10 additions & 0 deletions doc/man3/EVP_MAC.pod
Original file line number Diff line number Diff line change
Expand Up @@ -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().

Expand Down Expand Up @@ -344,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
Expand Down

0 comments on commit 7c1d533

Please sign in to comment.