mac: improve MAC documentation (Poly 1305 key reuse, nomenclature)

Fixes #12441

Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/15237)

diff --git a/doc/man3/EVP_MAC.pod b/doc/man3/EVP_MAC.pod
index f4386f9dafff712417b7ac035aee41d53d64418a..d053375dcf2fd5211d0173433ff4acd35ccd266d 100644 (file)
--- 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<OSSL_MAC_PARAM_IV>) <octet string>
 
-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<OSSL_MAC_PARAM_CUSTOM>) <octet string>
 
@@ -342,6 +342,8 @@ The MAC life-cycle is described in L<life_cycle-mac(7)>.  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 59f9444214a0a8c05fa70e3059f1f58887500d3c..a942226cd8aaff07d324d9c97326b26e173a54f4 100644 (file)
--- 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<unsigned int>.
 
+=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<EVP_MAC_CTX_get_params(3)>, L<EVP_MAC_CTX_set_params(3)>,