[openssl] master update
Dr. Paul Dale
pauli at openssl.org
Fri Mar 26 08:23:08 UTC 2021
The branch master has been updated
via 4551763efc8c9d2e39f3d39430cb4657d155cde6 (commit)
via 10b63e9756cf932cbaba5f725445a2a032a7f271 (commit)
via b0b63654e9da02a6f336c5660e659a87a29e916e (commit)
via 632bc4dff3856374192052871c39b24032b17728 (commit)
via 77d12ae049c21851b77ff6ee992a362b73a684c8 (commit)
via 2e1a40d0374a2bfc7478e4da5dd6739f7a127a72 (commit)
via 4aac71f705f5fff15c6cb0da44d9f8014f48901f (commit)
from 8c63532002fdab11b437bc8d68012c2b05cf00ea (commit)
- Log -----------------------------------------------------------------
commit 4551763efc8c9d2e39f3d39430cb4657d155cde6
Author: Pauli <pauli at openssl.org>
Date: Wed Mar 24 14:02:48 2021 +1000
doc: life-cycle descritpion for MACs
Reviewed-by: Tomas Mraz <tomas at openssl.org>
(Merged from https://github.com/openssl/openssl/pull/14522)
commit 10b63e9756cf932cbaba5f725445a2a032a7f271
Author: Pauli <pauli at openssl.org>
Date: Wed Mar 24 13:38:57 2021 +1000
doc: note that MAC lifecycle transitions will be enforced at some point
Reviewed-by: Tomas Mraz <tomas at openssl.org>
(Merged from https://github.com/openssl/openssl/pull/14522)
commit b0b63654e9da02a6f336c5660e659a87a29e916e
Author: Pauli <pauli at openssl.org>
Date: Wed Mar 24 13:35:41 2021 +1000
doc: life-cycle descritpion for RANDs
Reviewed-by: Tomas Mraz <tomas at openssl.org>
(Merged from https://github.com/openssl/openssl/pull/14522)
commit 632bc4dff3856374192052871c39b24032b17728
Author: Pauli <pauli at openssl.org>
Date: Wed Mar 24 13:12:40 2021 +1000
doc: note that RAND lifecycle transitions will be enforced at some point
Reviewed-by: Tomas Mraz <tomas at openssl.org>
(Merged from https://github.com/openssl/openssl/pull/14522)
commit 77d12ae049c21851b77ff6ee992a362b73a684c8
Author: Pauli <ppzgs1 at gmail.com>
Date: Fri Mar 12 09:46:56 2021 +1000
doc: life-cycle description for KDFs/PRFs
Reviewed-by: Tomas Mraz <tomas at openssl.org>
(Merged from https://github.com/openssl/openssl/pull/14522)
commit 2e1a40d0374a2bfc7478e4da5dd6739f7a127a72
Author: Pauli <ppzgs1 at gmail.com>
Date: Fri Mar 12 09:46:05 2021 +1000
doc: note that KDF/PRF transitions will be enforced at some future point
Reviewed-by: Tomas Mraz <tomas at openssl.org>
(Merged from https://github.com/openssl/openssl/pull/14522)
commit 4aac71f705f5fff15c6cb0da44d9f8014f48901f
Author: Pauli <ppzgs1 at gmail.com>
Date: Fri Mar 12 08:46:55 2021 +1000
doc: add life-cycle source files
Reviewed-by: Tomas Mraz <tomas at openssl.org>
(Merged from https://github.com/openssl/openssl/pull/14522)
-----------------------------------------------------------------------
Summary of changes:
doc/build.info | 18 ++++
doc/life-cycles/Makefile | 26 +++++
doc/life-cycles/README.md | 18 ++++
doc/life-cycles/cipher.dot | 72 ++++++++++++++
doc/life-cycles/digest.dot | 31 ++++++
doc/life-cycles/kdf.dot | 14 +++
doc/life-cycles/lifecycles.ods | Bin 0 -> 16408 bytes
doc/life-cycles/mac.dot | 24 +++++
doc/life-cycles/pkey.dot | 48 ++++++++++
doc/life-cycles/rand.dot | 15 +++
doc/man3/EVP_KDF.pod | 9 +-
doc/man3/EVP_MAC.pod | 11 ++-
doc/man3/EVP_RAND.pod | 7 +-
doc/man7/kdf.png | Bin 0 -> 29120 bytes
doc/man7/life_cycle-kdf.pod | 165 ++++++++++++++++++++++++++++++++
doc/man7/life_cycle-mac.pod | 210 +++++++++++++++++++++++++++++++++++++++++
doc/man7/life_cycle-rand.pod | 193 +++++++++++++++++++++++++++++++++++++
doc/man7/mac.png | Bin 0 -> 50554 bytes
doc/man7/provider-kdf.pod | 8 +-
doc/man7/provider-mac.pod | 10 +-
doc/man7/provider-rand.pod | 10 +-
doc/man7/rand.png | Bin 0 -> 41597 bytes
22 files changed, 882 insertions(+), 7 deletions(-)
create mode 100644 doc/life-cycles/Makefile
create mode 100644 doc/life-cycles/README.md
create mode 100644 doc/life-cycles/cipher.dot
create mode 100644 doc/life-cycles/digest.dot
create mode 100644 doc/life-cycles/kdf.dot
create mode 100644 doc/life-cycles/lifecycles.ods
create mode 100644 doc/life-cycles/mac.dot
create mode 100644 doc/life-cycles/pkey.dot
create mode 100644 doc/life-cycles/rand.dot
create mode 100644 doc/man7/kdf.png
create mode 100644 doc/man7/life_cycle-kdf.pod
create mode 100644 doc/man7/life_cycle-mac.pod
create mode 100644 doc/man7/life_cycle-rand.pod
create mode 100644 doc/man7/mac.png
create mode 100644 doc/man7/rand.png
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/life-cycles/Makefile b/doc/life-cycles/Makefile
new file mode 100644
index 0000000000..4c12558e63
--- /dev/null
+++ b/doc/life-cycles/Makefile
@@ -0,0 +1,26 @@
+GRAPHS=cipher.dot digest.dot kdf.dot mac.dot pkey.dot rand.dot
+IMAGES=
+
+all: png txt
+png: $(subst .dot,.png,$(GRAPHS))
+txt: $(subst .dot,.txt,$(GRAPHS))
+ @echo
+ @echo Remember to check and manually fix the mistakes before merging
+ @echo into the man pages.
+ @echo
+
+# for the dot program:
+# sudo apt install graphviz
+%.png: %.dot
+ dot -Tpng -O $<
+ @mv $<.png $@
+
+# for the graph-easy program:
+# sudo apt install cpanminus
+# sudo cpanm Graph::Easy
+%.txt: %.dot
+ graph-easy --from=dot --as_ascii < $< > $@
+
+clean:
+ rm -f $(wildcard *.png) $(wildcard *.txt)
+
diff --git a/doc/life-cycles/README.md b/doc/life-cycles/README.md
new file mode 100644
index 0000000000..d504396545
--- /dev/null
+++ b/doc/life-cycles/README.md
@@ -0,0 +1,18 @@
+This directory contains the algorithm life-cycle diagram sources.
+
+The canonical life-cycles are in the spreadsheet.
+
+The various .dot files are graph descriptions for the
+[GraphViz](https://www.graphviz.org/) tool. These omit edges and should
+be used for guidance only.
+
+To generate the rendered images, you need to install:
+``` sh
+sudo apt install graphviz cpanminus
+sudo cpanm Graph::Easy
+```
+
+Running `make` will produce a number of `.txt` and `.png` files.
+These are the rendered `.dot` files. The `.txt` files require
+additional editing before they can be added to the manual pages in
+`internal/man7/life_cycle-*.pod`.
diff --git a/doc/life-cycles/cipher.dot b/doc/life-cycles/cipher.dot
new file mode 100644
index 0000000000..6f1acb4026
--- /dev/null
+++ b/doc/life-cycles/cipher.dot
@@ -0,0 +1,72 @@
+digraph cipher {
+ begin [label=start, color="#deeaee", style="filled"];
+ newed [fontcolor="#c94c4c", style="solid"];
+
+ initialised [fontcolor="#c94c4c"];
+ updated [fontcolor="#c94c4c"];
+ finaled [fontcolor="#c94c4c"];
+ end [label="freed", color="#deeaee", style="filled"];
+
+ d_initialised [label="initialised\n(decryption)", fontcolor="#c94c4c"];
+ d_updated [label="updated\n(decryption)", fontcolor="#c94c4c"];
+ e_initialised [label="initialised\n(encryption)", fontcolor="#c94c4c"];
+ e_updated [label="updated\n(encryption)", fontcolor="#c94c4c"];
+
+ begin -> newed [label="EVP_CIPHER_CTX_new"];
+ newed -> initialised [label="EVP_CipherInit"];
+ initialised -> initialised [label="EVP_CipherInit\n(not required but allowed)",
+ style=dashed];
+ initialised -> updated [label="EVP_CipherUpdate", weight=2];
+ updated -> updated [label="EVP_CipherUpdate"];
+ updated -> finaled [label="EVP_CipherFinal"];
+ finaled -> finaled [label="EVP_CIPHER_CTX_get_params\n(AEAD encryption)",
+ style=dashed];
+ finaled -> end [label="EVP_CIPHER_CTX_free"];
+ finaled -> newed [label="EVP_CIPHER_CTX_reset", style=dashed,
+ color="#034f84", fontcolor="#034f84"];
+ updated -> newed [label="EVP_CIPHER_CTX_reset", style=dashed,
+ color="#034f84", fontcolor="#034f84"];
+ newed -> d_initialised [label="EVP_DecryptInit"];
+ d_initialised -> d_initialised [label="EVP_DecryptInit\n(not required but allowed)",
+ style=dashed];
+ d_initialised -> d_updated [label="EVP_DecryptUpdate", weight=2];
+ d_updated -> d_updated [label="EVP_DecryptUpdate"];
+ d_updated -> finaled [label="EVP_DecryptFinal"];
+ d_updated -> newed [label="EVP_CIPHER_CTX_reset", style=dashed,
+ color="#034f84", fontcolor="#034f84"];
+ newed -> e_initialised [label="EVP_EncryptInit"];
+ e_initialised -> e_initialised [label="EVP_EncryptInit\n(not required but allowed)",
+ style=dashed];
+ e_initialised -> e_updated [label="EVP_EncryptUpdate", weight=2];
+ e_updated -> e_updated [label="EVP_EncryptUpdate"];
+ e_updated -> finaled [label="EVP_EncryptFinal"];
+ e_updated -> newed [label="EVP_CIPHER_CTX_reset", style=dashed,
+ color="#034f84", fontcolor="#034f84"];
+}
+
+/* This is a version with a single flavour which is easier to comprehend
+digraph cipher {
+ begin [label=start, color="#deeaee", style="filled"];
+ newed [fontcolor="#c94c4c", style="solid"];
+ initialised [fontcolor="#c94c4c"];
+ updated [fontcolor="#c94c4c"];
+ finaled [fontcolor="#c94c4c"];
+ end [label="freed", color="#deeaee", style="filled"];
+
+ begin -> newed [label="EVP_CIPHER_CTX_new"];
+ newed -> initialised [label="EVP_CipherInit"];
+ initialised -> initialised [label="EVP_CipherInit\n(not required but allowed)",
+ style=dashed];
+ initialised -> updated [label="EVP_CipherUpdate", weight=2];
+ updated -> updated [label="EVP_CipherUpdate"];
+ updated -> finaled [label="EVP_CipherFinal"];
+ finaled -> finaled [label="EVP_CIPHER_CTX_get_params\n(AEAD encryption)",
+ style=dashed];
+ finaled -> end [label="EVP_CIPHER_CTX_free"];
+ finaled -> newed [label="EVP_CIPHER_CTX_reset", style=dashed,
+ color="#034f84", fontcolor="#034f84"];
+ updated -> newed [label="EVP_CIPHER_CTX_reset", style=dashed,
+ color="#034f84", fontcolor="#034f84"];
+}
+*/
+
diff --git a/doc/life-cycles/digest.dot b/doc/life-cycles/digest.dot
new file mode 100644
index 0000000000..989342fd10
--- /dev/null
+++ b/doc/life-cycles/digest.dot
@@ -0,0 +1,31 @@
+digraph digest {
+ begin [label=start, color="#deeaee", style="filled"];
+ newed [label=newed, fontcolor="#c94c4c", style="solid"];
+ initialised [label=initialised, fontcolor="#c94c4c"];
+ updated [label=updated, fontcolor="#c94c4c"];
+ finaled [label="finaled", fontcolor="#c94c4c"];
+ end [label="freed", color="#deeaee", style="filled"];
+
+ begin -> newed [label="EVP_MD_CTX_new"];
+ newed -> initialised [label="EVP_DigestInit"];
+ initialised -> updated [label="EVP_DigestUpdate", weight=3];
+ updated -> updated [label="EVP_DigestUpdate"];
+ updated -> finaled [label="EVP_DigestFinal"];
+ updated -> finaled [label="EVP_DigestFinalXOF",
+ fontcolor="#808080", color="#808080"];
+ /* Once this works it should go back in:
+ finaled -> finaled [taillabel="EVP_DigestFinalXOF",
+ labeldistance=9, labelangle=345,
+ labelfontcolor="#808080", color="#808080"];
+ */
+ finaled -> end [label="EVP_MD_CTX_free"];
+ finaled -> newed [label="EVP_MD_CTX_reset", style=dashed, weight=2,
+ color="#034f84", fontcolor="#034f84"];
+ updated -> newed [label="EVP_MD_CTX_reset", style=dashed,
+ color="#034f84", fontcolor="#034f84"];
+ updated -> initialised [label="EVP_DigestInit", weight=0, style=dashed,
+ color="#034f84", fontcolor="#034f84"];
+ finaled -> initialised [label="EVP_DigestInit", style=dashed,
+ color="#034f84", fontcolor="#034f84"];
+}
+
diff --git a/doc/life-cycles/kdf.dot b/doc/life-cycles/kdf.dot
new file mode 100644
index 0000000000..4729dcdeba
--- /dev/null
+++ b/doc/life-cycles/kdf.dot
@@ -0,0 +1,14 @@
+strict digraph kdf {
+ begin [label=start, color="#deeaee", style="filled"];
+ newed [label="newed", fontcolor="#c94c4c", style="solid"];
+ deriving [label="deriving", fontcolor="#c94c4c"];
+ end [label="freed", color="#deeaee", style="filled"];
+
+ begin -> newed [label="EVP_KDF_CTX_new"];
+ newed -> deriving [label="EVP_KDF_derive"];
+ deriving -> deriving [label="EVP_KDF_derive", style=dashed];
+ deriving -> end [label="EVP_KDF_CTX_free"];
+ deriving -> newed [label="EVP_KDF_CTX_reset", style=dashed,
+ color="#034f84", fontcolor="#034f84"];
+}
+
diff --git a/doc/life-cycles/lifecycles.ods b/doc/life-cycles/lifecycles.ods
new file mode 100644
index 0000000000..4f77f281e0
Binary files /dev/null and b/doc/life-cycles/lifecycles.ods differ
diff --git a/doc/life-cycles/mac.dot b/doc/life-cycles/mac.dot
new file mode 100644
index 0000000000..c52701742c
--- /dev/null
+++ b/doc/life-cycles/mac.dot
@@ -0,0 +1,24 @@
+digraph mac {
+ begin [label=start, color="#deeaee", style="filled"];
+ newed [fontcolor="#c94c4c", style="solid"];
+ initialised [fontcolor="#c94c4c"];
+ updated [fontcolor="#c94c4c"];
+ finaled [fontcolor="#c94c4c"];
+ end [label=freed, color="#deeaee", style="filled"];
+
+ begin -> newed [label="EVP_MAC_CTX_new"];
+ newed -> initialised [label="EVP_MAC_init"];
+ initialised -> updated [label="EVP_MAC_update"];
+ updated -> updated [label="EVP_MAC_update"];
+ updated -> finaled [label="EVP_MAC_final"];
+ /* Once this works it should go back in:
+ updated -> finaled [label="EVP_MAC_final_XOF", style=dashed];
+ finaled -> finaled [label="EVP_MAC_final_XOF", style=dashed];
+ */
+ finaled -> end [label="EVP_MAC_CTX_free"];
+ updated -> initialised [label="EVP_MAC_init", style=dashed,
+ color="#034f84", fontcolor="#034f84"];
+ finaled -> initialised [label="EVP_MAC_init", style=dashed,
+ color="#034f84", fontcolor="#034f84"];
+}
+
diff --git a/doc/life-cycles/pkey.dot b/doc/life-cycles/pkey.dot
new file mode 100644
index 0000000000..1662c4ef3d
--- /dev/null
+++ b/doc/life-cycles/pkey.dot
@@ -0,0 +1,48 @@
+strict digraph pkey {
+ layout=circo
+
+ begin [label=start, color="#deeaee", style="filled"];
+ newed [fontcolor="#c94c4c", style="solid"];
+ digestsign [label="digest sign", fontcolor="#AB3910", color="#AB3910"]
+ verify [fontcolor="#F8CF2C", color="#F8CF2C"]
+ verifyrecover [label="verify recover", fontcolor="#B19FF9", color="#B19FF9"]
+ encrypt [fontcolor="#63AAC0", color="#63AAC0"]
+ decrypt [fontcolor="#425F06", color="#425F06"]
+ derive [fontcolor="#FEA303", color="#FEA303"]
+ encapsulate [fontcolor="#D95980", color="#D95980"]
+ decapsulate [fontcolor="#A16AE8", color="#A16AE8"]
+ paramgen [label="parameter\ngeneration", fontcolor="#2879C0", color="#2879C0"]
+ keygen [label="key\ngeneration", fontcolor="#2F7604", color="#2F7604"]
+
+ begin -> newed [label="EVP_PKEY_CTX_new"];
+
+ newed -> digestsign [label="EVP_PKEY_sign_init", color="#AB3910", fontcolor="#AB3910"];
+ digestsign -> digestsign [label="EVP_PKEY_sign", color="#AB3910", fontcolor="#AB3910"];
+
+ newed -> verify [label="EVP_PKEY_verify_init", fontcolor="#F8CF2C", color="#F8CF2C"];
+ verify -> verify [label="EVP_PKEY_verify", fontcolor="#F8CF2C", color="#F8CF2C"];
+
+ newed -> verifyrecover [label="EVP_PKEY_verify_recover_init", fontcolor="#B19FF9", color="#B19FF9"];
+ verifyrecover -> verifyrecover [label="EVP_PKEY_verify_recover", fontcolor="#B19FF9", color="#B19FF9"];
+
+ newed -> encrypt [label="EVP_PKEY_encrypt_init", fontcolor="#63AAC0", color="#63AAC0"];
+ encrypt -> encrypt [label="EVP_PKEY_encrypt", fontcolor="#63AAC0", color="#63AAC0"];
+
+ newed -> decrypt [label="EVP_PKEY_decrypt_init", fontcolor="#425F06", color="#425F06"];
+ decrypt -> decrypt [label="EVP_PKEY_decrypt", fontcolor="#425F06", color="#425F06"];
+
+ newed -> derive [label="EVP_PKEY_derive_init", fontcolor="#FEA303", color="#FEA303"];
+ derive -> derive [label="EVP_PKEY_derive\nEVP_PKEY_derive_set_peer", fontcolor="#FEA303", color="#FEA303"];
+
+ newed -> encapsulate [label="EVP_PKEY_encapsulate_init", fontcolor="#D95980", color="#D95980"];
+ encapsulate -> encapsulate [label="EVP_PKEY_encapsulate", fontcolor="#D95980", color="#D95980"];
+
+ newed -> decapsulate [label="EVP_PKEY_decapsulate_init", fontcolor="#A16AE8", color="#A16AE8"];
+ decapsulate -> decapsulate [label="EVP_PKEY_decapsulate", fontcolor="#A16AE8", color="#A16AE8"];
+
+ newed -> paramgen [label="EVP_PKEY_paramgen_init", fontcolor="#2879C0", color="#2879C0"];
+ paramgen -> paramgen [label="EVP_PKEY_paramgen\nEVP_PKEY_gen", fontcolor="#2879C0", color="#2879C0"];
+
+ newed -> keygen [label="EVP_PKEY_keygen_init", fontcolor="#2F7604", color="#2F7604"];
+ keygen -> keygen [label="EVP_PKEY_keygen\nEVP_PKEY_gen", fontcolor="#2F7604", color="#2F7604"];
+}
diff --git a/doc/life-cycles/rand.dot b/doc/life-cycles/rand.dot
new file mode 100644
index 0000000000..5aa225f314
--- /dev/null
+++ b/doc/life-cycles/rand.dot
@@ -0,0 +1,15 @@
+strict digraph rand {
+ begin [label=start, color="#deeaee", style="filled"];
+ newed [fontcolor="#c94c4c", style="solid"];
+ instantiated [fontcolor="#c94c4c"];
+ uninstantiated [fontcolor="#c94c4c"];
+ end [label="freed", color="#deeaee", style="filled"];
+
+ begin -> newed [label="EVP_RAND_CTX_new"];
+ newed -> instantiated [label="EVP_RAND_instantiate"];
+ instantiated -> instantiated [label="EVP_RAND_generate"];
+ instantiated -> uninstantiated [label="EVP_RAND_uninstantiate"];
+ uninstantiated -> end [label="EVP_RAND_CTX_free"];
+ uninstantiated -> instantiated [label="EVP_RAND_instantiate", style=dashed, color="#034f84", fontcolor="#034f84"];
+}
+
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/man3/EVP_MAC.pod b/doc/man3/EVP_MAC.pod
index 928ef52407..b4ad7209dd 100644
--- 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/man3/EVP_RAND.pod b/doc/man3/EVP_RAND.pod
index 52cf5118d8..f550ec18e3 100644
--- a/doc/man3/EVP_RAND.pod
+++ b/doc/man3/EVP_RAND.pod
@@ -336,6 +336,10 @@ An B<EVP_RAND_CTX> needs to have locking enabled if it acts as the parent of
more than one child and the children can be accessed concurrently. This must
be done by explicitly calling EVP_RAND_enable_locking().
+The RAND life-cycle is described in L<life_cycle-rand(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_RAND_fetch() returns a pointer to a newly fetched B<EVP_RAND>, or
@@ -382,7 +386,8 @@ L<EVP_RAND-CTR-DRBG(7)>,
L<EVP_RAND-HASH-DRBG(7)>,
L<EVP_RAND-HMAC-DRBG(7)>,
L<EVP_RAND-TEST-RAND(7)>,
-L<provider-rand(7)>
+L<provider-rand(7)>,
+L<life_cycle-rand(7)>
=head1 HISTORY
diff --git a/doc/man7/kdf.png b/doc/man7/kdf.png
new file mode 100644
index 0000000000..3a3d153af0
Binary files /dev/null and b/doc/man7/kdf.png differ
diff --git a/doc/man7/life_cycle-kdf.pod b/doc/man7/life_cycle-kdf.pod
new file mode 100644
index 0000000000..7237c4c13e
--- /dev/null
+++ b/doc/man7/life_cycle-kdf.pod
@@ -0,0 +1,165 @@
+=pod
+
+=head1 NAME
+
+life_cycle-kdf - The KDF algorithm life-cycle
+
+=head1 DESCRIPTION
+
+All key derivation functions (KDFs) and pseudo random functions (PRFs)
+go through a number of stages in their life-cycle:
+
+=over 4
+
+=item start
+
+This state represents the KDF/PRF before it has been allocated. It is the
+starting state for any life-cycle transitions.
+
+=item newed
+
+This state represents the KDF/PRF after it has been allocated.
+
+=item deriving
+
+This state represents the KDF/PRF when it is set up and capable of generating
+output.
+
+=item freed
+
+This state is entered when the KDF/PRF is freed. It is the terminal state
+for all life-cycle transitions.
+
+=back
+
+=head2 State Transition Diagram
+
+The usual life-cycle of a KDF/PRF is illustrated:
+
+=begin man
+
+ +-------------------+
+ | start |
+ +-------------------+
+ |
+ | EVP_KDF_CTX_new
+ v
+ +-------------------+
+ | newed | <+
+ +-------------------+ |
+ | |
+ | EVP_KDF_derive |
+ v | EVP_KDF_CTX_reset
+ EVP_KDF_derive +-------------------+ |
+ + - - - - - - - - | | |
+ ' | deriving | |
+ + - - - - - - - -> | | -+
+ +-------------------+
+ |
+ | EVP_KDF_CTX_free
+ v
+ +-------------------+
+ | freed |
+ +-------------------+
+
+=end man
+
+=for html <img src="kdf.png">
+
+=head2 Formal State Transitions
+
+This section defines all of the legal state transitions.
+This is the canonical list.
+
+=begin man
+
+ Function Call ------------- Current State -------------
+ start newed deriving freed
+ EVP_KDF_CTX_new newed
+ EVP_KDF_derive deriving deriving
+ EVP_KDF_CTX_free freed freed freed
+ EVP_KDF_CTX_reset newed newed
+ EVP_KDF_CTX_get_params newed deriving
+ EVP_KDF_CTX_set_params newed deriving
+ EVP_KDF_CTX_gettable_params newed deriving
+ EVP_KDF_CTX_settable_params newed deriving
+
+=end man
+
+=begin html
+
+<table style="border:1px solid; border-collapse:collapse">
+<tr><th style="border:1px solid" align="left">Function Call</th>
+ <th style="border:1px solid" colspan="4">Current State</th></tr>
+<tr><th style="border:1px solid"></th>
+ <th style="border:1px solid" align="center">start</th>
+ <th style="border:1px solid" align="center">newed</th>
+ <th style="border:1px solid" align="center">deriving</th>
+ <th style="border:1px solid" align="center">freed</th></tr>
+<tr><th style="border:1px solid" align="left">EVP_KDF_CTX_new</th>
+ <td style="border:1px solid" align="center">newed</td>
+ <td style="border:1px solid"></td>
+ <td style="border:1px solid"></td>
+ <td style="border:1px solid"></td></tr>
+<tr><th style="border:1px solid" align="left">EVP_KDF_derive</th>
+ <td style="border:1px solid" align="center"></td>
+ <td style="border:1px solid" align="center">newed</td>
+ <td style="border:1px solid" align="center">deriving</td>
+ <td style="border:1px solid"></td></tr>
+<tr><th style="border:1px solid" align="left">EVP_KDF_CTX_free</th>
+ <td style="border:1px solid" align="center"></td>
+ <td style="border:1px solid" align="center">newed</td>
+ <td style="border:1px solid" align="center">deriving</td>
+ <td style="border:1px solid"></td></tr>
+<tr><th style="border:1px solid" align="left">EVP_KDF_CTX_reset</th>
+ <td style="border:1px solid" align="center">freed</td>
+ <td style="border:1px solid" align="center">freed</td>
+ <td style="border:1px solid" align="center">freed</td>
+ <td style="border:1px solid"></td></tr>
+<tr><th style="border:1px solid" align="left">EVP_KDF_CTX_get_params</th>
+ <td style="border:1px solid" align="center"></td>
+ <td style="border:1px solid" align="center">newed</td>
+ <td style="border:1px solid" align="center">deriving</td>
+ <td style="border:1px solid"></td></tr>
+<tr><th style="border:1px solid" align="left">EVP_KDF_CTX_set_params</th>
+ <td style="border:1px solid" align="center"></td>
+ <td style="border:1px solid" align="center">newed</td>
+ <td style="border:1px solid" align="center">deriving</td>
+ <td style="border:1px solid"></td></tr>
+<tr><th style="border:1px solid" align="left">EVP_KDF_CTX_gettable_params</th>
+ <td style="border:1px solid" align="center"></td>
+ <td style="border:1px solid" align="center">newed</td>
+ <td style="border:1px solid" align="center">deriving</td>
+ <td style="border:1px solid"></td></tr>
+<tr><th style="border:1px solid" align="left">EVP_KDF_CTX_settable_params</th>
+ <td style="border:1px solid" align="center"></td>
+ <td style="border:1px solid" align="center">newed</td>
+ <td style="border:1px solid" align="center">deriving</td>
+ <td style="border:1px solid"></td></tr>
+</table>
+
+=end html
+
+=head1 NOTES
+
+At some point the EVP layer will begin enforcing the transitions described
+herein.
+
+=head1 SEE ALSO
+
+L<provider-kdf(7)>, L<EVP_KDF(3)>.
+
+=head1 HISTORY
+
+The provider KDF interface was introduced in OpenSSL 3.0.
+
+=head1 COPYRIGHT
+
+Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
diff --git a/doc/man7/life_cycle-mac.pod b/doc/man7/life_cycle-mac.pod
new file mode 100644
index 0000000000..b9812f7cae
--- /dev/null
+++ b/doc/man7/life_cycle-mac.pod
@@ -0,0 +1,210 @@
+=pod
+
+=head1 NAME
+
+life_cycle-mac - The MAC algorithm life-cycle
+
+=head1 DESCRIPTION
+
+All message authentication codes (MACs)
+go through a number of stages in their life-cycle:
+
+=over 4
+
+=item start
+
+This state represents the MAC before it has been allocated. It is the
+starting state for any life-cycle transitions.
+
+=item newed
+
+This state represents the MAC after it has been allocated.
+
+=item initialised
+
+This state represents the MAC when it is set up and capable of processing
+input.
+
+=item updated
+
+This state represents the MAC when it is set up and capable of processing
+additional input or generating output.
+
+=item finaled
+
+This state represents the MAC when it has generated output.
+
+=item freed
+
+This state is entered when the MAC is freed. It is the terminal state
+for all life-cycle transitions.
+
+=back
+
+=head2 State Transition Diagram
+
+The usual life-cycle of a MAC is illustrated:
+
+=begin man
+
+ +-------------------+
+ | start |
+ +-------------------+
+ |
+ | EVP_MAC_CTX_new
+ v
+ +-------------------+
+ | newed |
+ +-------------------+
+ |
+ | EVP_MAC_init
+ v
+ +-------------------+
+ +> | initialised | <+
+ | +-------------------+ |
+ | | |
+ | | EVP_MAC_update | EVP_MAC_init
+ | v |
+ EVP_MAC_init | +-------------------+ |
+ | | updated | -+
+ | +-------------------+
+ | |
+ | | EVP_MAC_final
+ | v
+ | +-------------------+
+ +- | finaled |
+ +-------------------+
+ |
+ | EVP_MAC_CTX_free
+ v
+ +-------------------+
+ | freed |
+ +-------------------+
+
+=end man
+
+=for html <img src="mac.png">
+
+=head2 Formal State Transitions
+
+This section defines all of the legal state transitions.
+This is the canonical list.
+
+=begin man
+
+ Function Call ------------- Current State -------------
+ start newed initialised updated finaled freed
+ EVP_MAC_CTX_new newed
+ EVP_MAC_init initialised initialised initialised initialised
+ EVP_MAC_update updated updated
+ EVP_MAC_final finaled
+ EVP_MAC_CTX_free freed freed freed freed freed
+ EVP_MAC_gettable_ctx_params newed initialised updated
+ EVP_MAC_settable_ctx_params newed initialised updated
+ EVP_MAC_CTX_gettable_params newed initialised updated
+ EVP_MAC_CTX_settable_params newed initialised updated
+
+=end man
+
+=begin html
+
+<table style="border:1px solid; border-collapse:collapse">
+<tr><th style="border:1px solid" align="left">Function Call</th>
+ <th style="border:1px solid" colspan="6">Current State</th></tr>
+<tr><th style="border:1px solid"></th>
+ <th style="border:1px solid" align="center">start</th>
+ <th style="border:1px solid" align="center">newed</th>
+ <th style="border:1px solid" align="center">initialised</th>
+ <th style="border:1px solid" align="center">updated</th>
+ <th style="border:1px solid" align="center">finaled</th>
+ <th style="border:1px solid" align="center">freed</th></tr>
+<tr><th style="border:1px solid" align="left">EVP_MAC_CTX_new</th>
+ <td style="border:1px solid" align="center">newed</td>
+ <td style="border:1px solid" align="center"></td>
+ <td style="border:1px solid" align="center"></td>
+ <td style="border:1px solid" align="center"></td>
+ <td style="border:1px solid" align="center"></td>
+ <td style="border:1px solid" align="center"></td></tr>
+<tr><th style="border:1px solid" align="left">EVP_MAC_init</th>
+ <td style="border:1px solid" align="center"></td>
+ <td style="border:1px solid" align="center">initialised</td>
+ <td style="border:1px solid" align="center">initialised</td>
+ <td style="border:1px solid" align="center">initialised</td>
+ <td style="border:1px solid" align="center">initialised</td>
+ <td style="border:1px solid" align="center"></td></tr>
+<tr><th style="border:1px solid" align="left">EVP_MAC_update</th>
+ <td style="border:1px solid" align="center"></td>
+ <td style="border:1px solid" align="center"></td>
+ <td style="border:1px solid" align="center">updated</td>
+ <td style="border:1px solid" align="center">updated</td>
+ <td style="border:1px solid" align="center"></td>
+ <td style="border:1px solid" align="center"></td></tr>
+<tr><th style="border:1px solid" align="left">EVP_MAC_final</th>
+ <td style="border:1px solid" align="center"></td>
+ <td style="border:1px solid" align="center"></td>
+ <td style="border:1px solid" align="center"></td>
+ <td style="border:1px solid" align="center">finaled</td>
+ <td style="border:1px solid" align="center"></td>
+ <td style="border:1px solid" align="center"></td></tr>
+<tr><th style="border:1px solid" align="left">EVP_MAC_CTX_free</th>
+ <td style="border:1px solid" align="center">freed</td>
+ <td style="border:1px solid" align="center">freed</td>
+ <td style="border:1px solid" align="center">freed</td>
+ <td style="border:1px solid" align="center">freed</td>
+ <td style="border:1px solid" align="center">freed</td>
+ <td style="border:1px solid" align="center"></td></tr>
+<tr><th style="border:1px solid" align="left">EVP_MAC_gettable_ctx_params</th>
+ <td style="border:1px solid" align="center"></td>
+ <td style="border:1px solid" align="center">newed</td>
+ <td style="border:1px solid" align="center">initialised</td>
+ <td style="border:1px solid" align="center">updated</td>
+ <td style="border:1px solid" align="center"></td>
+ <td style="border:1px solid" align="center"></td></tr>
+<tr><th style="border:1px solid" align="left">EVP_MAC_settable_ctx_params</th>
+ <td style="border:1px solid" align="center"></td>
+ <td style="border:1px solid" align="center">newed</td>
+ <td style="border:1px solid" align="center">initialised</td>
+ <td style="border:1px solid" align="center">updated</td>
+ <td style="border:1px solid" align="center"></td>
+ <td style="border:1px solid" align="center"></td></tr>
+<tr><th style="border:1px solid" align="left">EVP_MAC_CTX_gettable_params</th>
+ <td style="border:1px solid" align="center"></td>
+ <td style="border:1px solid" align="center">newed</td>
+ <td style="border:1px solid" align="center">initialised</td>
+ <td style="border:1px solid" align="center">updated</td>
+ <td style="border:1px solid" align="center"></td>
+ <td style="border:1px solid" align="center"></td></tr>
+<tr><th style="border:1px solid" align="left">EVP_MAC_CTX_settable_params</th>
+ <td style="border:1px solid" align="center"></td>
+ <td style="border:1px solid" align="center">newed</td>
+ <td style="border:1px solid" align="center">initialised</td>
+ <td style="border:1px solid" align="center">updated</td>
+ <td style="border:1px solid" align="center"></td>
+ <td style="border:1px solid" align="center"></td></tr>
+</table>
+
+=end html
+
+=head1 NOTES
+
+At some point the EVP layer will begin enforcing the transitions described
+herein.
+
+=head1 SEE ALSO
+
+L<provider-mac(7)>, L<EVP_MAC(3)>.
+
+=head1 HISTORY
+
+The provider MAC interface was introduced in OpenSSL 3.0.
+
+=head1 COPYRIGHT
+
+Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
diff --git a/doc/man7/life_cycle-rand.pod b/doc/man7/life_cycle-rand.pod
new file mode 100644
index 0000000000..b78b8484d2
--- /dev/null
+++ b/doc/man7/life_cycle-rand.pod
@@ -0,0 +1,193 @@
+=pod
+
+=head1 NAME
+
+life_cycle-rand - The RAND algorithm life-cycle
+
+=head1 DESCRIPTION
+
+All random number generator (RANDs)
+go through a number of stages in their life-cycle:
+
+=over 4
+
+=item start
+
+This state represents the RAND before it has been allocated. It is the
+starting state for any life-cycle transitions.
+
+=item newed
+
+This state represents the RAND after it has been allocated but unable to
+generate any output.
+
+=item instantiated
+
+This state represents the RAND when it is set up and capable of generating
+output.
+
+=item uninstantiated
+
+This state represents the RAND when it has been shutdown and it is no longer
+capable of generating output.
+
+=item freed
+
+This state is entered when the RAND is freed. It is the terminal state
+for all life-cycle transitions.
+
+=back
+
+=head2 State Transition Diagram
+
+The usual life-cycle of a RAND is illustrated:
+
+=begin man
+
+ +-------------------------+
+ | start |
+ +-------------------------+
+ |
+ | EVP_RAND_CTX_new
+ v
+ +-------------------------+
+ | newed |
+ +-------------------------+
+ |
+ | EVP_RAND_instantiate
+ v
+ EVP_RAND_generate +-------------------------+
+ +-------------------- | |
+ | | instantiated |
+ +-------------------> | | <+
+ +-------------------------+ '
+ | '
+ | EVP_RAND_uninstantiate ' EVP_RAND_instantiate
+ v '
+ +-------------------------+ '
+ | uninstantiated | -+
+ +-------------------------+
+ |
+ | EVP_RAND_CTX_free
+ v
+ +-------------------------+
+ | freed |
+ +-------------------------+
+
+=end man
+
+=for html <img src="rand.png">
+
+=head2 Formal State Transitions
+
+This section defines all of the legal state transitions.
+This is the canonical list.
+
+=begin man
+
+ Function Call ------------------ Current State ------------------
+ start newed instantiated uninstantiated freed
+ EVP_RAND_CTX_new newed
+ EVP_RAND_instantiate instantiated
+ EVP_RAND_generate instantiated
+ EVP_RAND_uninstantiate uninstantiated
+ EVP_RAND_CTX_free freed freed freed freed
+ EVP_RAND_get_ctx_params newed instantiated uninstantiated freed
+ EVP_RAND_set_ctx_params newed instantiated uninstantiated freed
+ EVP_RAND_CTX_gettable_params newed instantiated uninstantiated freed
+ EVP_RAND_CTX_settable_params newed instantiated uninstantiated freed
+
+=end man
+
+=begin html
+
+<table style="border:1px solid; border-collapse:collapse">
+<tr><th style="border:1px solid" align="left">Function Call</th>
+ <th style="border:1px solid" colspan="5">Current State</th></tr>
+<tr><th style="border:1px solid"></th>
+ <th style="border:1px solid" align="center">start</th>
+ <th style="border:1px solid" align="center">newed</th>
+ <th style="border:1px solid" align="center">instantiated</th>
+ <th style="border:1px solid" align="center">uninstantiated</th>
+ <th style="border:1px solid" align="center">freed</th></tr>
+<tr><th style="border:1px solid" align="left">EVP_RAND_CTX_new</th>
+ <td style="border:1px solid" align="center">newed</td>
+ <td style="border:1px solid" align="center"></td>
+ <td style="border:1px solid" align="center"></td>
+ <td style="border:1px solid" align="center"></td>
+ <td style="border:1px solid" align="center"></td></tr>
+<tr><th style="border:1px solid" align="left">EVP_RAND_instantiate</th>
+ <td style="border:1px solid" align="center"></td>
+ <td style="border:1px solid" align="center">instantiated</td>
+ <td style="border:1px solid" align="center"></td>
+ <td style="border:1px solid" align="center"></td>
+ <td style="border:1px solid" align="center"></td></tr>
+<tr><th style="border:1px solid" align="left">EVP_RAND_generate</th>
+ <td style="border:1px solid" align="center"></td>
+ <td style="border:1px solid" align="center"></td>
+ <td style="border:1px solid" align="center">instantiated</td>
+ <td style="border:1px solid" align="center"></td>
+ <td style="border:1px solid" align="center"></td></tr>
+<tr><th style="border:1px solid" align="left">EVP_RAND_uninstantiate</th>
+ <td style="border:1px solid" align="center"></td>
+ <td style="border:1px solid" align="center"></td>
+ <td style="border:1px solid" align="center">uninstantiated</td>
+ <td style="border:1px solid" align="center"></td>
+ <td style="border:1px solid" align="center"></td></tr>
+<tr><th style="border:1px solid" align="left">EVP_RAND_CTX_free</th>
+ <td style="border:1px solid" align="center">freed</td>
+ <td style="border:1px solid" align="center">freed</td>
+ <td style="border:1px solid" align="center">freed</td>
+ <td style="border:1px solid" align="center">freed</td>
+ <td style="border:1px solid" align="center"></td></tr>
+<tr><th style="border:1px solid" align="left">EVP_RAND_get_ctx_params</th>
+ <td style="border:1px solid" align="center"></td>
+ <td style="border:1px solid" align="center">newed</td>
+ <td style="border:1px solid" align="center">instantiated</td>
+ <td style="border:1px solid" align="center">uninstantiated</td>
+ <td style="border:1px solid" align="center"></td></tr>
+<tr><th style="border:1px solid" align="left">EVP_RAND_set_ctx_params</th>
+ <td style="border:1px solid" align="center"></td>
+ <td style="border:1px solid" align="center">newed</td>
+ <td style="border:1px solid" align="center">instantiated</td>
+ <td style="border:1px solid" align="center">uninstantiated</td>
+ <td style="border:1px solid" align="center"></td></tr>
+<tr><th style="border:1px solid" align="left">EVP_RAND_CTX_gettable_params</th>
+ <td style="border:1px solid" align="center"></td>
+ <td style="border:1px solid" align="center">newed</td>
+ <td style="border:1px solid" align="center">instantiated</td>
+ <td style="border:1px solid" align="center">uninstantiated</td>
+ <td style="border:1px solid" align="center"></td></tr>
+<tr><th style="border:1px solid" align="left">EVP_RAND_CTX_settable_params</th>
+ <td style="border:1px solid" align="center"></td>
+ <td style="border:1px solid" align="center">newed</td>
+ <td style="border:1px solid" align="center">instantiated</td>
+ <td style="border:1px solid" align="center">uninstantiated</td>
+ <td style="border:1px solid" align="center"></td></tr>
+</table>
+
+=end html
+
+=head1 NOTES
+
+At some point the EVP layer will begin enforcing the transitions described
+herein.
+
+=head1 SEE ALSO
+
+L<provider-rand(7)>, L<EVP_RAND(3)>.
+
+=head1 HISTORY
+
+The provider RAND interface was introduced in OpenSSL 3.0.
+
+=head1 COPYRIGHT
+
+Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
diff --git a/doc/man7/mac.png b/doc/man7/mac.png
new file mode 100644
index 0000000000..1c486e1ba4
Binary files /dev/null and b/doc/man7/mac.png differ
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
diff --git a/doc/man7/provider-mac.pod b/doc/man7/provider-mac.pod
index 82bbdb9aa2..1f7810c16c 100644
--- 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
diff --git a/doc/man7/provider-rand.pod b/doc/man7/provider-rand.pod
index be81237610..951f483b60 100644
--- a/doc/man7/provider-rand.pod
+++ b/doc/man7/provider-rand.pod
@@ -272,11 +272,19 @@ error.
All of the remaining functions should return 1 for success or 0 on error.
+=head1 NOTES
+
+The RAND 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 SEE ALSO
L<provider(7)>,
L<RAND(7)>,
-L<EVP_RAND(7)>
+L<EVP_RAND(7)>,
+L<life_cycle-rand(7)>,
+L<EVP_RAND(3)>
=head1 HISTORY
diff --git a/doc/man7/rand.png b/doc/man7/rand.png
new file mode 100644
index 0000000000..56d213f389
Binary files /dev/null and b/doc/man7/rand.png differ
More information about the openssl-commits
mailing list