From b9d0b9f2296e0de89bde1a0a6336d84cff4d7827 Mon Sep 17 00:00:00 2001
From: Dustin Lundquist <dustin@null-ptr.net>
Date: Sat, 3 Feb 2018 11:38:52 -0800
Subject: [PATCH] Describe ttyspy and ttyspyd in README

---
 README.md | 55 ++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 52 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 5451ed1..3f99689 100644
--- a/README.md
+++ b/README.md
@@ -20,9 +20,21 @@ the architecture and configuration.
 ## Client
 
 The client functions as script(1) with the typescript output file piped to
-curl(1). Originally it was going to be implemented by wrapping these two
-utilities using a named pipe between the two, but the non-deterministic order
-in which these utilities would open the pipe prevented this method.
+curl(1). Originally implemented by wrapping these two utilities using a named
+pipe between the two, but the non-deterministic order in which these utilities
+would open the pipe prevented this method.
+
+The client and server use TLS mutual certificate authentication. In order to
+prevent an unprivileged user from obtaining the client's certificate private
+key the client is separated into two processes: ttyspy and ttyspyd. Otherwise a
+malicious user could forge transcripts implicating other users or DoS the
+session_receiver server.
+
+TTYspyd runs as a user with access to the client private key and accepts
+connections on a UNIX socket. It then looks up the connecting user, establishes
+a connection to the session_receiver server and includes HTTP headers
+specifying the user and hostname.
+
 
 ### Dependencies
 
@@ -38,6 +50,43 @@ autoreconf --install
 make
 ```
 
+### Installation
+
+A certificate authority for ttyspy clients should be established. These will be
+used to authenticate clients connecting to the session_receiver server. Both
+ttyspy and ttyspyd user a common configuration file: /etc/ttyspy/ttyspy.conf.
+
+    # User which ttyspyd runs as
+    username       daemon
+
+    # Unix socket where ttyspy client connect to ttyspyd and ttyspyd listens
+    # for clients
+    socket         /tmp/ttyspy.sock
+
+    # URL of transcript archive server running session_receiver
+    endpoint       https://server.test/transcript
+
+    # TLS certificate authority to validate session_receiver's server
+    # certificate against
+    ca_path        /etc/ttyspy/ca.pem
+
+    # TLS certificate used by ttyspyd to authenticate
+    cert_path      /etc/ttyspy/client.pem
+
+    # TLS private key used by ttyspyd to authenticate, this may point to a
+    # single PEM file containing the certificate and private key. This file's
+    # permission should be restricted so users can not read the private key.
+    key_path       /etc/ttyspy/client.pem
+
+This configuration contains directives that only apply to ttyspyd, and are
+simply ignored by ttyspy. Arrangements should be made for ttyspyd be started
+automatically at boot.
+
+For interactive session logging, arrangements should be made to invoke ttyspy
+at login such as sshd's ForceCommand directive e.g. `ForceCommand
+/usr/bin/ttyspy`.
+
+
 ## Server
 
 The server is a simple Go webserver which authenticates client connections by