Add an embryo for system documentation.

Trying ot document the add-chain process.

1 files changed, 41 insertions, 0 deletions

diff --git a/doc/system.md b/doc/system.md
new file mode 100644
index 0000000..d5670d5
--- /dev/null
+++ b/doc/system.md
@@ -0,0 +1,41 @@
+# This document
+
+This document contains system documentation of catlfish and plop.
+
+Note that this document is far from complete. Don't draw any
+conclusions from missing topics.
+
+## A certificate chain is being submitted to a frontend node
+
+External HTTP endpoint ct/v1/add-chain [RFC6962 sect 4.1] has one
+input element "chain" which is an array of base64-encoded
+certificates.
+
+The certificate chain is verified and normalised and a "duplicate
+check" is done using plop:get() with a hash over the whole chain. If
+the entry isn't already present in the database or if a matching SCT
+signature is not found in the SCT cache,
+
+- the entry is added -- plop:add()
+- an SCT signature is retrieved from a signing node -- plop:spt\_sig()
+- the SCT signature is added to the SCT cache -- plop:add\_spt\_sig()
+
+If the entry wasn't already present in the database, the entry is
+"committed" by calling plop:commit() which calls internal API
+storage/entrycommitted on all storage nodes.
+
+Internal API storage/entrycommitted passes contents of the
+"timestamp\_signature" header to plop:add\_spt() which
+
+- adds the leafhash to the entryhash key-value store, for retrieval of
+  leafhash given an entry (used in the duplicate check)
+- adds the SPT signature to the SPT cache, i.e. the SCT cache for
+  catlfish
+
+Internal API storage/sendentry returns a "sig" header with
+<KeyName>:<Signature>. The signature is returned by plop:add() to
+catlfish for later use in call to plop:commit().
+
+Internal API signing/sct verifies the signatures in the "signatures"
+header, counts proper signatures against configured storage sign
+quorum and calls its own gen\_server for an SCT signature.