X-Git-Url: https://git.distorted.org.uk/~mdw/tripe/blobdiff_plain/5ae728a6a2bb6db57a8586e839221cc33cf9c69c..18969e42a11e11ef8a3ea81eaf0038e8e74e004d:/server/tripe-admin.5.in

diff --git a/server/tripe-admin.5.in b/server/tripe-admin.5.in
index 86fe3149..3e7bd8ef 100644
--- a/server/tripe-admin.5.in
+++ b/server/tripe-admin.5.in
@@ -363,18 +363,18 @@ sends us something before responding.
 .TP
 .B "\-ephemeral"
 The association with the peer is not intended to persist indefinitely.
-If a peer marked as ephemeral is killed, or the
+When a peer is killed, or the
 .BR tripe (8)
-daemon is shut down, send a
+daemon is shut down, a
 .B bye
-packet to the peer so that it forgets about us; if a peer marked as
-ephemeral sends us a
+packet is to the peer(s).  If a peer marked as ephemeral sends us a
 .B bye
 packet then it is killed (but in this case no further
 .B bye
-packet is sent).  Peers not marked as ephemeral exhibit neither of these
-behaviours; each peer must have the other marked as ephemeral for the
-association to be fully torn down if either end kills the other.
+packet is sent).  A
+.B bye
+packet from a peer which isn't marked as ephemeral leaves the peer alone
+in the hope that the connection can be reestablished.
 .TP
 .BI "\-keepalive " time
 Send a no-op packet if we've not sent a packet to the peer in the last
@@ -414,7 +414,7 @@ emits a
 .B KNOCK
 notification stating the peer's (claimed) name and address.  The server
 will already have verified that the sender is using the peer's private
-key by this point.  This option implies
+key by this point.  Prior to version 1.6.0, this option used to imply
 .BR \-ephemeral .
 .TP
 .B "\-mobile"
@@ -425,7 +425,7 @@ peers, however, it will attempt to decrypt the packet using their keys,
 and if one succeeds, the server will update its idea of the peer's
 address and emit an
 .B NEWADDR
-notification.  This option implies
+notification.  Prior to version 1.6.0, this option used to imply
 .BR \-ephemeral .
 .TP
 .BI "\-priv " tag
@@ -571,10 +571,24 @@ responses are the same as for the
 .B PING
 command.
 .SP
-.BI "FORCEKX " peer
+.BI "FORCEKX \fR[" options "\fR] " peer
 Requests the server to begin a new key exchange with
 .I peer
-immediately.
+immediately.  The following options are recognized.
+.RS
+.\"+opts
+.TP
+.B "\-quiet"
+Don't actually start a new key exchange; just quietly mark any previous
+key exchange as stale so that a fresh attempt from the peer will
+succeed.  This is was introduced for use during testing, but it's also
+useful when a remote peer has forgotten about us: it would be
+annoying if, once it's learns about us and tries to reinitiate a key
+exchange, we ignore it because we think we've already done one recently;
+on the other hand, forcing a key exchange before the remote peer has
+been reinformed about us is a waste of packets.
+.\"-opts
+.RE
 .SP
 .B "GETCHAL"
 Requests a challenge.  The challenge is returned in an
@@ -614,9 +628,24 @@ line giving the tag for each outstanding background job.
 .BI "KILL " peer
 Causes the server to forget all about
 .IR peer .
-All keys are destroyed, and no more packets are sent.  No notification
-is sent to the peer: if it's important that the peer be notified, you
-must think of a way to do that yourself.
+All keys are destroyed, and no more packets are sent.  A
+.B bye
+message is sent to the peer if it's marked as
+.B "\-ephemeral"
+\(en see the
+.B "ADD"
+command.  The following options are
+recognized.
+.RS
+.\"+opts
+.TP
+.B "\-quiet"
+Suppress any
+.B bye
+message to an ephemeral peer: just quietly forget about it.  This is
+used during testing, and is not expected to be generally useful.
+.\"-opts
+.RE
 .SP
 .B "LIST"
 For each currently-known peer, an
@@ -1060,7 +1089,9 @@ string was invalid.
 of arguments was wrong.
 .SP
 .BI "bad-time-spec " token
-The
+(For commands accepting a
+.I time
+argument.)  The
 .I token
 is not a valid time interval specification.  Acceptable time
 specifications are nonnegative integers followed optionally by
@@ -1086,6 +1117,12 @@ An unknown watch option was requested.
 .BR DAEMON .)
 An error occurred during the attempt to become a daemon, as reported by
 .IR message .
+See
+.B WARNINGS
+below for the meanings of
+.I ecode
+and
+.IR message .
 .SP
 .BI "disabled-address-family " afam
 (For
@@ -1129,6 +1166,8 @@ There is already a peer named
 .IR peer .
 .SP
 .B "ping-send-failed"
+(For
+.BR EPING .)
 The attempt to send a ping packet failed, probably due to lack of
 encryption keys.
 .SP
@@ -1359,6 +1398,16 @@ core in its configuration directory.
 .BI "ABORT repeated-select-errors"
 The main event loop is repeatedly failing.  If the server doesn't quit,
 it will probably waste all available CPU doing nothing.
+.SP
+.BI "ABORT hash-size-too-large hash " name " size " sz " limit " max
+An internal inconsistency: the hash function
+.I name
+produces a
+.IR sz -byte
+hash, but the server has been compiled to assume that no hash function
+returns more than
+.I max
+bytes.
 .SS "ADMIN warnings"
 These indicate a problem with the administration socket interface.
 .SP
@@ -1429,7 +1478,7 @@ command or in greeting packets.
 .SP
 .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.
+thought they could make one up is hard to imagine.
 .SP
 .B "CHAL incorrect-tag"
 Challenge received contained the wrong authentication data.  It might be
@@ -1458,9 +1507,6 @@ and the second token is the filename of the keyring.  Frequently a key
 tag may be given next, preceded by the token
 .BR key .
 .SP
-.BI "KEYMGMT private-keyring " file " key " tag " incorrect-public-key"
-The private key doesn't record the correct corresponding public key.
-.SP
 .BI "KEYMGMT public-keyring " file " key " tag " algorithm-mismatch"
 A peer's public key doesn't request the same algorithms as our private
 key.
@@ -1476,19 +1522,28 @@ The key attributes contain
 .I str
 where a MAC tag length was expected.  The key was generated wrongly.
 .SP
+.BI "KEYMGMT private-keyring " file " key " tag " incorrect-public-key"
+The private key doesn't record the correct corresponding public key.
+.SP
+.BI "KEYMGMT " which "-keyring " file " io-error " ecode " " message
+A system error occurred while opening or reading the keyring file.
+.SP
 .BI "KEYMGMT private-keyring " file " key " tag " changed-group"
 The private keyring has been changed, but the new private key can't be
 used because it uses a different group for Diffie\(enHellman key
 exchange.
 .SP
-.BI "KEYMGMT " which "-keyring " file " io-error " ecode " " message
-A system error occurred while opening or reading the keyring file.
+.BI "KEYMGMT " which "-keyring " file " key " tag " no-hmac-for-hash " hash
+No message authentication code was given explicitly, and there's no
+implementation of HMAC for the selected hash function
+.IR hash .
 .SP
 .BI "KEYMGMT " which "-keyring " file " key " tag " unknown-bulk-transform " bulk
 The key specifies the use of an unknown bulk-crypto transform
 .IR bulk .
-Maybe the key was generated wrongly, or maybe the version of Catacomb
-installed is too old.
+Maybe the key was generated wrongly, or maybe the version of
+.BR tripe (8)
+is too old.
 .SP
 .BI "KEYMGMT " which "-keyring " file " key " tag " unknown-cipher " cipher
 The key specifies the use of an unknown symmetric encryption algorithm
@@ -1525,12 +1580,54 @@ version of Catacomb installed is too old.
 The key specifies the use of an unknown serialization format
 .I ser
 for hashing group elements.  Maybe the key was generated wrongly, or
-maybe the version of Catacomb installed is too old.
+maybe the version of
+.BR tripe (8)
+is too old.
 .SP
-.BI "KEYMGMT " which "-keyring " file " key " tag " no-hmac-for-hash " hash
-No message authentication code was given explicitly, and there's no
-implementation of HMAC for the selected hash function
-.IR hash .
+.BI "KEYMGMT " which "-keyring " file " key " tag " unsuitable-aead-cipher " cipher "no-aad"
+The key specifies the use of an authenticated encryption scheme
+.I cipher
+which does not support the processing of additional authenticated data.
+The most prominent examples of such schemes are the
+.IB cipher -naclbox
+collection, where
+.I cipher
+is
+.BR salsa20 ,
+.BR salsa20/12 ,
+.BR salsa20/8 ,
+.BR chacha20 ,
+.BR chacha12 ,
+or
+.BR chacha8 ;
+use the
+.B naclbox
+bulk transform rather than
+.B aead
+for these, or switch to one of the IETF
+.IB cipher -poly1305
+schemes instead.
+.SP
+.BI "KEYMGMT " which "-keyring " file " key " tag " unsuitable-aead-cipher " cipher "nonce-too-small"
+The key specifies the use of an authenticated encryption scheme
+.I cipher
+which doesn't even allow a 5-byte (40-bit) nonce.  Catacomb doesn't
+implement any such limited AE schemes: you must be doing something
+strange.
+.SP
+.BI "KEYMGMT " which "-keyring " file " key " tag " unsuitable-aead-cipher " cipher "nonce-too-large"
+The key specifies the use of an authenticated encryption scheme
+.I cipher
+which doesn't support any nonce size smaller than 64 bytes (512 bits).
+Catacomb doesn't implement any such extravagant AE schemes: you must be
+doing something strange.
+.SP
+.BI "KEYMGMT " which "-keyring " file " key " tag " unsuitable-aead-cipher " cipher "nonempty-ciphertext-for-empty-message"
+The key specifies the use of an authenticated encryption scheme
+.I cipher
+which produces ciphertext output even when given a completely empty
+message.  Catacomb doesn't implement any such unhelpful AE schemes: you
+must be doing something strange.
 .SP
 .BI "KEYMGMT " which "-keyring " file " key " tag " " alg " " name " no-key-size " hashsz
 The