server/: Prepare an interface for multiple bulk-crypto transforms.

[tripe] / server / tripe-admin.5.in

diff --git a/server/tripe-admin.5.in b/server/tripe-admin.5.in
index 5b0fe3bef03ed66a46ebc810a11c4e7a374d37e0..aeafc63e5b19510111286ae5a287046615e68a75 100644 (file)
--- a/server/tripe-admin.5.in
+++ b/server/tripe-admin.5.in
@@ -364,6 +364,19 @@ address and emit an
 .B NEWADDR
 notification.
 .TP
 .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
 .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
 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
 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
 .RS

+.PP
+The keys are as follows.

 .TP
 .B kx-group
 Type of key-exchange group in use, currently either
 .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 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 .
 .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.,
 .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
 .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
 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
 .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
 .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
 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
 .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
 .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
 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
 .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
 .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
 .I tag

-wasn't in the public keyring.
+couldn't be found in the keyring.

 .SP
 .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
 .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
 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
 .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
 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
 .SP
 .BI "KX " peer " sending-cookie"
 We've received too many bogus pre-challenge messages.  Someone is trying