From d68dad3be28bd83b4c7b8c144fda78dc1b75ec26 Mon Sep 17 00:00:00 2001
From: Joey Hess <joeyh@joeyh.name>
Date: Tue, 2 May 2017 18:02:34 -0400
Subject: add page

---
 doc/evidence.mdwn       |  36 ++++++++++++++++++++++++++++++++++++
 doc/evidence/laggy.png  | Bin 0 -> 59620 bytes
 doc/evidence/simple.png | Bin 0 -> 66620 bytes
 doc/index.mdwn          |   1 +
 4 files changed, 37 insertions(+)
 create mode 100644 doc/evidence.mdwn
 create mode 100644 doc/evidence/laggy.png
 create mode 100644 doc/evidence/simple.png

diff --git a/doc/evidence.mdwn b/doc/evidence.mdwn
new file mode 100644
index 0000000..8c5a309
--- /dev/null
+++ b/doc/evidence.mdwn
@@ -0,0 +1,36 @@
+A debug-me log file is evidence of what happened in a debug-me session.
+It shows what the developer who connected to the server saw, and what the
+developer did.
+
+The log file uses an Ed25519 session key that is signed by the developer's
+Gnupg key, so everything the developer did in the session is effectively
+signed by their Gnupg key. It's impossible to generate a log file that
+shows a developer doing something other than what they did, unless you
+have the developer's Gnupg private key.
+
+The log file is formatted as a series of JSON objects, and includes both
+messages from the user's debug-me, and from the developer's debug-me. See
+[[protocol]] for more details about the messages.
+
+The important thing is that each message points to the SHA256 hash of a
+previous message, which builds up a chain. This chain can be
+verified by simply checking the hashes.
+
+## graphing debug-me sessions
+
+The chain of activities can be visualized by running `debug-me --graphviz
+logfile`.
+
+Here are two examples. In both of these, the shell started, the developer
+typed "echo hi" and then saw the output of the command, and then ended the
+session with control-d.
+
+[[!simple]] [[!laggy]]
+
+The difference between the two sessions is that the one 
+on the right went over a laggy network connection. In the middle of its
+graph, you can see that the developer typed "h", and before that letter
+echoed back, went on to type "o ". Thus, the chain splits to reflect the
+different perspectives of the local and remote debug-me programs at that
+point. Since they were able to agree on a resolution, the chain then 
+merges back together.
diff --git a/doc/evidence/laggy.png b/doc/evidence/laggy.png
new file mode 100644
index 0000000..6df0322
Binary files /dev/null and b/doc/evidence/laggy.png differ
diff --git a/doc/evidence/simple.png b/doc/evidence/simple.png
new file mode 100644
index 0000000..dc37286
Binary files /dev/null and b/doc/evidence/simple.png differ
diff --git a/doc/index.mdwn b/doc/index.mdwn
index f594425..1051a53 100644
--- a/doc/index.mdwn
+++ b/doc/index.mdwn
@@ -5,6 +5,7 @@
 * [[Bugs]]
 * [[Todo]]
 * [[Protocol]]
+* [[Evidence]]
 * [[Servers]]
 """]]
 
-- 
cgit v1.2.3