From: Pauli Date: Thu, 11 Mar 2021 22:46:55 +0000 (+1000) Subject: doc: add life-cycle source files X-Git-Tag: openssl-3.0.0-alpha14~125 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=4aac71f705f5fff15c6cb0da44d9f8014f48901f;p=thirdparty%2Fopenssl.git doc: add life-cycle source files Reviewed-by: Tomas Mraz (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 index 00000000000..4c12558e63d --- /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 00000000000..d5043965455 --- /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 00000000000..6f1acb40266 --- /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 00000000000..989342fd109 --- /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 00000000000..4729dcdeba7 --- /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 00000000000..4f77f281e0c 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 00000000000..c52701742ca --- /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 00000000000..1662c4ef3dd --- /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 00000000000..5aa225f314b --- /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"]; +} +