doc: note that MAC lifecycle transitions will be enforced at some point

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

diff --git a/doc/man3/EVP_MAC.pod b/doc/man3/EVP_MAC.pod
index 928ef524073f39a8422e259e370b5031d703188d..b4ad7209dd7cbb143b2a383149ce4601c494537a 100644 (file)
--- a/doc/man3/EVP_MAC.pod
+++ b/doc/man3/EVP_MAC.pod
@@ -304,6 +304,13 @@ EVP_MAC_init(), EVP_MAC_update() and EVP_MAC_final() for a full
 computation.
 Anything else may give undefined results.
 
+=head1 NOTES
+
+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.
+
+
 =head1 RETURN VALUES
 
 EVP_MAC_fetch() returns a pointer to a newly fetched EVP_MAC, or
@@ -428,7 +435,9 @@ L<EVP_MAC-GMAC(7)>,
 L<EVP_MAC-HMAC(7)>,
 L<EVP_MAC-KMAC(7)>,
 L<EVP_MAC-Siphash(7)>,
-L<EVP_MAC-Poly1305(7)>
+L<EVP_MAC-Poly1305(7)>,
+L<provider-mac(7)>,
+L<life_cycle-mac(7)>
 
 =head1 HISTORY
 

diff --git a/doc/man7/provider-mac.pod b/doc/man7/provider-mac.pod
index 82bbdb9aa24d4cae52f7b34df54f84db4a37fae6..1f7810c16cf77e4ef709df025217f39d26d0a9fb 100644 (file)
--- a/doc/man7/provider-mac.pod
+++ b/doc/man7/provider-mac.pod
@@ -185,6 +185,12 @@ should have as well, see the documentation of the implementation.
 
 =back
 
+=head1 NOTES
+
+The MAC life-cycle is described in L<life_cycle-rand(7)>.  Providers should
+ensure that the various transitions listed there are supported.  At some point
+the EVP layer will begin enforcing the listed transitions.
+
 =head1 RETURN VALUES
 
 OSSL_FUNC_mac_newctx() and OSSL_FUNC_mac_dupctx() should return the newly created
@@ -203,8 +209,8 @@ array, or NULL if none is offered.
 L<provider(7)>,
 L<EVP_MAC-BLAKE2(7)>, L<EVP_MAC-CMAC(7)>, L<EVP_MAC-GMAC(7)>,
 L<EVP_MAC-HMAC(7)>, L<EVP_MAC-KMAC(7)>, L<EVP_MAC-Poly1305(7)>,
-L<EVP_MAC-Siphash(7)>
-
+L<EVP_MAC-Siphash(7)>,
+L<life_cycle-mac(7)>, L<EVP_MAC(3)>
 
 =head1 HISTORY