From 0a12aba18f705c888d661d2e2da3848a392f70a5 Mon Sep 17 00:00:00 2001 From: Neil Horman Date: Mon, 8 Jan 2024 14:29:52 -0500 Subject: Update Docs for EVP_MAC 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 Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/23235) (cherry picked from commit 7c1d533a512181b13de3bc0b7fa2fd8c481032d3) --- doc/man3/EVP_MAC.pod | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/doc/man3/EVP_MAC.pod b/doc/man3/EVP_MAC.pod index 56ac92a486..762c0175ff 100644 --- a/doc/man3/EVP_MAC.pod +++ b/doc/man3/EVP_MAC.pod @@ -145,6 +145,9 @@ the key. If I is NULL, the key must be set via I either as part of this call or separately using EVP_MAC_CTX_set_params(). Providing non-NULL I to this function is equivalent to calling EVP_MAC_CTX_set_params() with those I for the same I 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(). @@ -342,6 +345,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 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 was initially generated. For such instances, an +B 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, or -- cgit v1.2.3