doc: add life-cycle source files

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

diff --git a/doc/life-cycles/Makefile b/doc/life-cycles/Makefile
new file mode 100644 (file)
index 0000000..4c12558
--- /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 (file)
index 0000000..d504396
--- /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 (file)
index 0000000..6f1acb4
--- /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 (file)
index 0000000..989342f
--- /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 (file)
index 0000000..4729dcd
--- /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 (file)
index 0000000..4f77f28
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 (file)
index 0000000..c527017
--- /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 (file)
index 0000000..1662c4e
--- /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 (file)
index 0000000..5aa225f
--- /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"];
+}
+