doc: note that KDF/PRF transitions will be enforced at some future point

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

3 files changed, 33 insertions, 2 deletions

diff --git a/doc/build.info b/doc/build.info
index 8294725dd2..48730cf945 100644
--- a/doc/build.info
+++ b/doc/build.info
@@ -4202,6 +4202,18 @@ DEPEND[html/man7/evp.html]=man7/evp.pod
 GENERATE[html/man7/evp.html]=man7/evp.pod
 DEPEND[man/man7/evp.7]=man7/evp.pod
 GENERATE[man/man7/evp.7]=man7/evp.pod
+DEPEND[html/man7/life_cycle-kdf.html]=man7/life_cycle-kdf.pod
+GENERATE[html/man7/life_cycle-kdf.html]=man7/life_cycle-kdf.pod
+DEPEND[man/man7/life_cycle-kdf.7]=man7/life_cycle-kdf.pod
+GENERATE[man/man7/life_cycle-kdf.7]=man7/life_cycle-kdf.pod
+DEPEND[html/man7/life_cycle-mac.html]=man7/life_cycle-mac.pod
+GENERATE[html/man7/life_cycle-mac.html]=man7/life_cycle-mac.pod
+DEPEND[man/man7/life_cycle-mac.7]=man7/life_cycle-mac.pod
+GENERATE[man/man7/life_cycle-mac.7]=man7/life_cycle-mac.pod
+DEPEND[html/man7/life_cycle-rand.html]=man7/life_cycle-rand.pod
+GENERATE[html/man7/life_cycle-rand.html]=man7/life_cycle-rand.pod
+DEPEND[man/man7/life_cycle-rand.7]=man7/life_cycle-rand.pod
+GENERATE[man/man7/life_cycle-rand.7]=man7/life_cycle-rand.pod
 DEPEND[html/man7/openssl-core.h.html]=man7/openssl-core.h.pod
 GENERATE[html/man7/openssl-core.h.html]=man7/openssl-core.h.pod
 DEPEND[man/man7/openssl-core.h.7]=man7/openssl-core.h.pod
@@ -4390,6 +4402,9 @@ html/man7/crypto.html \
 html/man7/ct.html \
 html/man7/des_modes.html \
 html/man7/evp.html \
+html/man7/life_cycle-kdf.html \
+html/man7/life_cycle-mac.html \
+html/man7/life_cycle-rand.html \
 html/man7/openssl-core.h.html \
 html/man7/openssl-core_dispatch.h.html \
 html/man7/openssl-core_names.h.html \
@@ -4489,6 +4504,9 @@ man/man7/crypto.7 \
 man/man7/ct.7 \
 man/man7/des_modes.7 \
 man/man7/evp.7 \
+man/man7/life_cycle-kdf.7 \
+man/man7/life_cycle-mac.7 \
+man/man7/life_cycle-rand.7 \
 man/man7/openssl-core.h.7 \
 man/man7/openssl-core_dispatch.h.7 \
 man/man7/openssl-core_names.h.7 \
diff --git a/doc/man3/EVP_KDF.pod b/doc/man3/EVP_KDF.pod
index c5309dc430..5d7fa72b16 100644
--- a/doc/man3/EVP_KDF.pod
+++ b/doc/man3/EVP_KDF.pod
@@ -279,9 +279,16 @@ The remaining functions return 1 for success and 0 or a negative value for
 failure.  In particular, a return value of -2 indicates the operation is not
 supported by the KDF algorithm.
 
+=head1 NOTES
+
+The KDF life-cycle is described in L<life_cycle-kdf(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 SEE ALSO
 
-L<OSSL_PROVIDER-default(7)/Key Derivation Function (KDF)>
+L<OSSL_PROVIDER-default(7)/Key Derivation Function (KDF)>,
+L<life_cycle-kdf(7)>.
 
 =head1 HISTORY
 
diff --git a/doc/man7/provider-kdf.pod b/doc/man7/provider-kdf.pod
index fb9e30a843..a13f3b108c 100644
--- a/doc/man7/provider-kdf.pod
+++ b/doc/man7/provider-kdf.pod
@@ -318,9 +318,15 @@ OSSL_FUNC_kdf_gettable_params(), OSSL_FUNC_kdf_gettable_ctx_params() and
 OSSL_FUNC_kdf_settable_ctx_params() should return a constant B<OSSL_PARAM>
 array, or NULL if none is offered.
 
+=head1 NOTES
+
+The KDF life-cycle is described in L<life_cycle-kdf(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 SEE ALSO
 
-L<provider(7)>
+L<provider(7)>, L<life_cycle-kdf(7)>, L<EVP_KDF(3)>.
 
 =head1 HISTORY