From: Pauli Date: Wed, 12 May 2021 02:26:24 +0000 (+1000) Subject: mac: improve MAC documentation (Poly 1305 key reuse, nomenclature) X-Git-Tag: openssl-3.0.0-alpha17~117 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=bbf5ccfd8729120e067de709c43be0a4cdfb423b;p=thirdparty%2Fopenssl.git mac: improve MAC documentation (Poly 1305 key reuse, nomenclature) Fixes #12441 Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/15237) --- diff --git a/doc/man3/EVP_MAC.pod b/doc/man3/EVP_MAC.pod index f4386f9daff..d053375dcf2 100644 --- a/doc/man3/EVP_MAC.pod +++ b/doc/man3/EVP_MAC.pod @@ -259,7 +259,7 @@ must be set first, see parameter names "algorithm" below. =item "iv" (B) -Some MAC implementations require an IV, this parameter sets the IV. +Some MAC implementations (GMAC) require an IV, this parameter sets the IV. =item "custom" (B) @@ -342,6 +342,8 @@ The MAC life-cycle is described in L. In the future, the transitions described there will be enforced. When this is done, it will 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. =head1 RETURN VALUES diff --git a/doc/man7/EVP_MAC-Poly1305.pod b/doc/man7/EVP_MAC-Poly1305.pod index 59f9444214a..a942226cd8a 100644 --- a/doc/man7/EVP_MAC-Poly1305.pod +++ b/doc/man7/EVP_MAC-Poly1305.pod @@ -49,6 +49,13 @@ Gets the MAC size. The "size" parameter can also be retrieved with with EVP_MAC_CTX_get_mac_size(). The length of the "size" parameter should not exceed that of an B. +=head1 NOTES + +The OpenSSL implementation of the Poly 1305 MAC corresponds to RFC 7539. + +It is critical to never reuse the key. The security implication noted in +RFC 8439 applies equally to the OpenSSL implementation. + =head1 SEE ALSO L, L,