openssl
/
openssl
mirror of https://github.com/openssl/openssl
1
0
Fork 0
Code Issues Releases Wiki Activity

doc: add life-cycle source files 

Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/14522)
This commit is contained in:
Pauli 2021-03-12 08:46:55 +10:00 committed by Pauli
parent 8c63532002
commit 4aac71f705
9 changed files with 248 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
doc/life-cycles/Makefile Normal file
View File

@ -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)

18
doc/life-cycles/README.md Normal file
View File

@ -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`.

72
doc/life-cycles/cipher.dot Normal file
View File

@ -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"];
}
*/

31
doc/life-cycles/digest.dot Normal file
View File

@ -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"];
}

14
doc/life-cycles/kdf.dot Normal file
View File

@ -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"];
}

BIN
doc/life-cycles/lifecycles.ods Normal file
View File

Binary file not shown.

24
doc/life-cycles/mac.dot Normal file
View File

@ -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"];
}

48
doc/life-cycles/pkey.dot Normal file
View File

@ -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"];
}

15
doc/life-cycles/rand.dot Normal file
View File

@ -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"];
}