X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/tripe/blobdiff_plain/6411163d48434575eaf49463e056e971a2fba16a..a93aacce200e0d68b614d8bfb05d9cbeba850b12:/server/tripe-admin.5.in

diff --git a/server/tripe-admin.5.in b/server/tripe-admin.5.in
index 5b0fe3be..aeafc63e 100644
--- a/server/tripe-admin.5.in
+++ b/server/tripe-admin.5.in
@@ -364,6 +364,19 @@ address and emit an
 .B NEWADDR
 notification.
 .TP
+.BI "\-priv " tag
+Use the private key
+.I tag
+to authenticate to the peer.  The default is to use the key named in the
+.RB ` \-t '
+command-line option, or a key with type
+.B tripe
+or
+.BR tripe-dh :
+see
+.BR tripe (8)
+for the details.
+.TP
 .BI "\-tunnel " tunnel
 Use the named tunnel driver, rather than the default.
 .\"-opts
@@ -375,10 +388,15 @@ Emits an
 line reporting the IP address and port number stored for
 .IR peer .
 .SP
-.B "ALGS"
+.BI "ALGS \fR[" peer \fR]
 Emits information about the cryptographic algorithms in use, in
-key-value form.  The keys are as follows.
+key-value form.  If a
+.I peer
+is given, then describe the algorithms used in the association with that
+peer; otherwise describe the default algorithms.
 .RS
+.PP
+The keys are as follows.
 .TP
 .B kx-group
 Type of key-exchange group in use, currently either
@@ -405,6 +423,12 @@ The mask-generating function in use, e.g.,
 .B hashsz
 The size of the hash function's output, in octets.
 .TP
+.B bulk-transform
+The name of the bulk-crypto transform.
+.TP
+.B bulk-overhead
+The amount of overhead, in bytes, caused by the crypto transform.
+.TP
 .B cipher
 The name of the bulk data cipher in use, e.g.,
 .BR blowfish-cbc .
@@ -423,7 +447,7 @@ allow for a seamless changeover of keys.)
 .TP
 .B mac
 The message authentication algorithm in use, e.g.,
-.BR ripemd160-hmac ..
+.BR ripemd160-hmac .
 .TP
 .B mac-keysz
 The length of the key used by the message authentication algorithm, in
@@ -438,13 +462,12 @@ tunnel interface.  If
 is the MTU of the path to the peer, then the tunnel MTU should be
 .IP
 .I MTU
-\- 33 \-
-.I cipher-blksz
-\-
-.I mac-tagsz
+\- 29 \-
+.I bulk-overhead
 .PP
 allowing 20 bytes of IP header, 8 bytes of UDP header, a packet type
-octet, a four-octet sequence number, an IV, and a MAC tag.
+octet, and the bulk-crypto transform overhead (which includes the
+sequence number).
 .RE
 .SP
 .BI "BGCANCEL " tag
@@ -541,10 +564,27 @@ The keepalive interval, in seconds, or zero if no keepalives are to be
 sent.
 .TP
 .B key
-The key tag being used for the peer, as passed to the
+The (short) key tag being used for the peer, as passed to the
+.B ADD
+command.
+.TP
+.B current-key
+The full key tag of the peer's public key currently being used.  This
+may change during the life of the association.
+.TP
+.B private-key
+The private key tag being used for the peer, as passed to the
 .B ADD
-command.  (You don't get a full key-id, since that might change while
-the daemon's running.)
+command, or the
+.RB ` \-t '
+command-line option.  If neither of these was given explicitly, the
+private key tag is shown as
+.RB ` (default) ',
+since there is no fixed tag used under these circumstances.
+.TP
+.B current-private-key
+The full key tag of the private key currently being used for this
+association.  This may change during the life of the association.
 .RE
 .SP
 .BI "PING \fR[" options "\fR] " peer
@@ -1192,58 +1232,107 @@ up to something!
 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.
-.SP
-.BI "KEYMGMT bad-private-key " message
-The private key could not be read, or failed a consistency check.  If
-there was a problem with the file, usually there will have been
-.B key-file-error
-warnings before this.
-.SP
-.BI "KEYMGMT bad-public-keyring " message
-The public keyring couldn't be read.  Usually, there will have been
-.B key-file-error
-warnings before this.
-.SP
-.BI "KEYMGMT key-file-error " file ":" line " " message
-Reports a specific error with the named keyring file.  This probably
-indicates a bug in
-.BR key (1).
-.SP
-.BI "KEYMGMT public-key " tag " " tokens\fR...
-These messages all indicate a problem with the public key named
-.IR tag .
-.SP
-.BI "KEYMGMT public-key " tag " algorithm-mismatch"
-The algorithms specified on the public key don't match the ones for our
-private key.  All the peers in a network have to use the same
-algorithms.
-.SP
-.BI "KEYMGMT public-key " tag " bad " message
-The public key couldn't be read, or is invalid.
-.SP
-.BI "KEYMGMT public-key " tag " bad-public-group-element"
-The public key is invalid.  This may indicate a malicious attempt to
-introduce a bogus key.
-.SP
-.BI "KEYMGMT public-key " tag " bad-algorithm-selection"
-The algorithms listed on the public key couldn't be understood.  The
-algorithm selection attributes are probably malformed and need fixing.
+them.  The first token is either
+.B private-keyring
+or
+.B public-keyring
+(notated
+.IB which -keyring
+in the descriptions below) indicating which keyring file is problematic,
+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 public-keyring " file " key " tag " algorithm-mismatch"
+A peer's public key doesn't request the same algorithms as our private
+key.
+.SP
+.BI "KEYMGMT " which "-keyring " file " key " tag " bad-tag-length " len
+The key attributes specify the length of MAC tag as
+.I len
+but this is an invalid value \(en either too large or not a multiple of
+eight.
+.SP
+.BI "KEYMGMT " which "-keyring " file " key " tag " bad-tag-length-string " str
+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 " 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.
+.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.
+.SP
+.BI "KEYMGMT " which "-keyring " file " key " tag " unknown-cipher " cipher
+The key specifies the use of an unknown symmetric encryption algorithm
+.IR cipher .
+Maybe the key was generated wrongly, or maybe the version of
+Catacomb installed is too old.
+.SP
+.BI "KEYMGMT " which "-keyring " file " key " tag " unknown-group-type " type
+The key specifies the use of a Diffie\(enHellman group of an unknown
+.IR type .
+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-hash " hash
+The key specifies the use of an unknown hash function
+.IR hash .
+Maybe the key was generated wrongly, or maybe the version of Catacomb
+installed is too old.
+.SP
+.BI "KEYMGMT " which "-keyring " file " key " tag " unknown-mac " mac
+The key specifies the use of an unknown message authentication code
+.IR mac .
+Maybe the key was generated wrongly, or maybe the version of Catacomb
+installed is too old.
+.SP
+.BI "KEYMGMT " which "-keyring " file " key " tag " unknown-mgf-cipher " mgf
+The key specifies the use of an unknown symmetric encryption function
+.I mgf
+for mask generation.  Maybe the key was generated wrongly, or maybe the
+version of Catacomb installed 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 .
+.SP
+.BI "KEYMGMT " which "-keyring " file " key " tag " " alg " " name " no-key-size " hashsz
+The
+.I alg
+token is either
+.B cipher
+or
+.BR mac .
+The named algorithm requires more key material than the hash function
+can provide.  You must change either the hash function, or the cipher or
+MAC.
 .SP
-.BI "KEYMGMT public-key " tag " incorrect-group"
-The public key doesn't use the same group as our private key.  All the
-peers in a network have to use the same group.
+.BI "KEYMGMT " which "-keyring " file " key " tag " mgf " mgf " restrictive-key-schedule"
+The cipher selected for mask-generation is unsuitable because it can't
+accept arbitrary-sized keys.
 .SP
-.BI "KEYMGMT public-key " tag " not-found"
-The public key for peer
+.BI "KEYMGMT " which "-keyring " file " key-not-found " tag
+A key named
 .I tag
-wasn't in the public keyring.
+couldn't be found in the keyring.
 .SP
-.BI "KEYMGMT public-key " tag " unknown-type"
-The type of the public key isn't understood.  Maybe you need to upgrade
-your copy of
-.BR tripe .
-(Even if you do, you'll have to regenerate your keys.)
+.BI "KEYMGMT " which "-keyring " file " line " line " " message
+The contents of the keyring file are invalid.  There may well be a bug
+in the
+.BR key (1)
+program.
 .SS "KX warnings"
 These indicate problems during key-exchange.  Many indicate either a bug
 in the server (either yours or the remote one), or some kind of attack
@@ -1263,6 +1352,12 @@ is one of the tokens
 or
 .BR switch-ok .
 .SP
+.BI "KX " peer " algorithms-mismatch local-private-key " privtag " peer-public-key " pubtag
+The algorithms specified in the peer's public key
+.I pubtag
+don't match the ones described in the private key
+.IR privtag .
+.SP
 .BI "KX " peer " bad-expected-reply-log"
 The challenges
 .B tripe
@@ -1286,9 +1381,11 @@ A message didn't contain the right magic data.  This may be a replay of
 some old exchange, or random packets being sent in an attempt to waste
 CPU.
 .SP
-.BI "KX " peer " public-key-expired"
-The peer's public key has expired.  It's maintainer should have given
-you a replacement before now.
+.BI "KX " peer " " which "-key-expired"
+The local private key or the peer's public key (distinguished by
+.IR which )
+has expired.  Either you or the peer's maintainer should have arranged
+for a replacement before now.
 .SP
 .BI "KX " peer " sending-cookie"
 We've received too many bogus pre-challenge messages.  Someone is trying