Improve terminology and documentationmain

1 files changed, 23 insertions, 0 deletions

diff --git a/docs/feedback.md b/docs/feedback.md
new file mode 100644
index 0000000..d79d57f
--- /dev/null
+++ b/docs/feedback.md
@@ -0,0 +1,23 @@
+# Feedback
+
+This document describes the integrity-protected file format that a trusted
+system uses when making legitimately issued certificates available to a monitor.
+
+## Format
+
+    NAME MAC
+    <CERTIFICATE CHAIN>
+    ...
+    <CERTIFICATE CHAIN>
+
+`NAME`: identifier that the monitor uses to locate the shared secret.
+
+`MAC`: HMAC with SHA256 as the hash function, computed for line two and forward.
+The shared HMAC key is derived as follows by the trusted system and the monitor:
+
+    hkdf := hkdf.New(sha256.New, SECRET, []byte("silentct"), NAME)
+    key := make([]byte, 16)
+    io.ReadFull(hkdf, key)
+
+`<CERTIFICATE CHAIN>`: certificate chain in PEM format that the trusted system
+considers legitimate.  Can be repeated, then delimited by "silentct:separator".