add page

4 files changed, 37 insertions, 0 deletions

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
--- /dev/null
+++ b/doc/evidence/laggy.png
diff --git a/doc/evidence/simple.png b/doc/evidence/simple.png
new file mode 100644
index 0000000..dc37286
--- /dev/null
+++ b/doc/evidence/simple.png
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]]
 """]]