infra: Clean up project setup

[tripe] / doc / tripe-admin.5

diff --git a/doc/tripe-admin.5 b/doc/tripe-admin.5
index b6bcdfc..4afa6a9 100644 (file)
--- a/doc/tripe-admin.5
+++ b/doc/tripe-admin.5
@@ -24,10 +24,9 @@ with little difficulty.
 By default, the server listens for admin connections on the Unix-domain
 socket
 .BR /var/lib/tripe/tripesock .
-Administration commands use a simple textual protocol.  Each client
-command or server response consists of a line of ASCII text terminated
-by a single linefeed character.  No command may be longer than 255
-characters.
+Administration commands use a textual protocol.  Each client command or
+server response consists of a line of ASCII text terminated by a single
+linefeed character.  No command may be longer than 255 characters.
 .SS "General structure"
 Each command or response line consists of a sequence of
 whitespace-separated words.  The number and nature of whitespace
@@ -251,6 +250,13 @@ Emits an
 line reporting the IP address and port number stored for
 .IR peer .
 .TP
+.BI "CHECKCHAL " challenge
+Verifies a challenge as being one earlier issued by
+.B GETCHAL
+and not previously either passed to
+.B CHECKCHAL
+or in a greeting message.
+.TP
 .B "DAEMON"
 Causes the server to disassociate itself from its terminal and become a
 background task.  This only works once.  A warning is issued.
@@ -268,6 +274,20 @@ Requests the server to begin a new key exchange with
 .I peer
 immediately.
 .TP
+.B "GETCHAL"
+Requests a challenge.  The challenge is returned in an
+.B INFO
+line, as a base64-encoded string.  See
+.BR CHECKCHAL .
+.TP
+.BI "GREET " peer " " challenge
+Sends a greeting packet containing the
+.I challenge
+(base-64 encoded) to the named
+.IR peer .
+The expectation is that this will cause the peer to recognize us and
+begin a key-exchange.
+.TP
 .B "HELP"
 Causes the server to emit an
 .B INFO
@@ -425,15 +445,6 @@ the backgroud name-resolution required by the
 .B ADD
 command.
 .TP
-.B p
-Display contents of packets sent and received by the tunnel and/or peer
-modules.
-.TP
-.B c
-Display inputs, outputs and intermediate results of cryptographic
-operations.  This includes plaintext and key material.  Use with
-caution.
-.TP
 .B s
 Handling of symmetric keysets: creation and expiry of keysets, and
 encryption and decryption of messages.
@@ -443,6 +454,21 @@ Key exchange: reception, parsing and emission of key exchange messages.
 .TP
 .B m
 Key management: loading keys and checking for file modifications.
+.TP
+.B l
+Display information about challenge issuing and verification.
+.TP
+.B p
+Display contents of packets sent and received by the tunnel and/or peer
+modules.
+.TP
+.B c
+Display inputs, outputs and intermediate results of cryptographic
+operations.  This includes plaintext and key material.  Use with
+caution.
+.TP
+.B A
+All of the above.
 .PP
 Note that the
 .B p
@@ -453,19 +479,17 @@ and
 outputs provide extra detail for other outputs.  Specifying
 .B p
 without
-.B r
+.BR r
 or
 .B t
 isn't useful; neither is specifying
 .B c
 without one of
 .BR s ,
+.BR l ,
 .B x
 or
 .BR m .
-.TP
-.B A
-All of the above.
 .RE
 .TP
 .B "TUNNELS"
@@ -507,7 +531,7 @@ messages.
 .B WARN
 messages.
 .TP
-.B a
+.B A
 All of the above.
 .RE
 .TP
@@ -530,6 +554,10 @@ The
 .B tripe
 server is already running as a daemon.
 .TP
+.BI "bad-addr-syntax \-\- " message
+(For commands accepting socket addresses.)  The address couldn't be
+understood.
+.TP
 .BI "bad-syntax \-\- " message
 (For any command.)  The command couldn't be understood: e.g., the number
 of arguments was wrong.
@@ -635,6 +663,12 @@ and its network address is
 .BI "DAEMON"
 The server has forked off into the sunset and become a daemon.
 .TP
+.BI "GREET " challenge " " address \fR...
+A valid greeting was received, with the given challenge (exactly as it
+was returned by
+.B GETCHAL
+earlier).
+.TP
 .BI "KILL " peer
 The peer
 .I peer
@@ -677,6 +711,29 @@ client.
 .BI "ADMIN client-read-error \-\- " message
 There was an error sending data to a client.  The connection to the
 client has been closed.
+.SS "CHAL warnings"
+These indicate errors in challenges, either in the
+.B CHECKCHAL
+command or in greeting packets.
+.TP
+.B "CHAL impossible-challenge"
+The server hasn't issued any challenges yet.  Quite how anyone else
+thought he could make one up is hard to imagine.
+.TP
+.B "CHAL incorrect-tag"
+Challenge received contained the wrong authentication data.  It might be
+very stale, or a forgery.
+.TP
+.B "CHAL invalid-challenge"
+Challenge received was the wrong length.  We might have changed MAC
+algorithms since the challenge was issued, or it might just be rubbish.
+.TP
+.B "CHAL replay duplicated-sequence"
+Challenge received was a definite replay of an old challenge.  Someone's
+up to something!
+.TP
+.B "CHAL replay old-sequence"
+Challenge received was old, but maybe not actually a replay.  Try again.
 .SS "KEYMGMT warnings"
 These indicate a problem with the keyring files, or the keys stored in
 them.