.\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
.
.\"--------------------------------------------------------------------------
-.so ../defs.man.in \" @@@PRE@@@
+.so ../common/defs.man \" @@@PRE@@@
.
.\"--------------------------------------------------------------------------
-.TH tripe-admin 5 "18 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
+.TH tripe-admin 5tripe "18 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
.
.\"--------------------------------------------------------------------------
.SH "NAME"
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
-characters separating two words in a client command is not significant;
-the server always uses a single space character. The first word in a
+whitespace-separated tokens. The number and nature of whitespace
+characters separating two tokens in a client command is not significant;
+the server always uses a single space character. The first token in a
line is a
.I keyword
identifying the type of command or response contained. Keywords in
client commands are not case-sensitive; the server always uses uppercase
for its keywords.
+.PP
+In order to allow tokens to contain internal whitespace, a quoting
+mechanism is provided. Whitespace within matched pairs of quotes \(en
+either single
+.RB ` ' '
+or double
+.RB ` """" '
+\(en is considered to be internal. Any character (other than newline)
+may be escaped by preceding it with a backslash
+.RB ` \e ':
+in particular, this can be used to include quote characters. It is
+impossible for a token to contain a newline character.
+.PP
+On output, the server will use double quotes when necessary.
.SS "Simple commands"
For simple client command, the server responds with zero or more
.B INFO
A background command will never issue an
.B OK
or
-.B BGINFO
+.B INFO
response: it will always detach and then issue any
.B BGINFO
lines followed by
.SP
.BI "SVCCLAIM " service " " version
Another client has claimed a later version of the named
-.I service. The recipient is no longer the provider of this service.
+.IR service .
+The recipient is no longer the provider of this service.
.SP
.BI "SVCJOB " jobid " " service " " command " " args \fR...
Announces the arrival of a new job. The
.BR BG ...
responses when appropriate.)
.SS "Network addresses"
-A network address is a sequence of words. The first is a token
+A network address is a sequence of tokens. The first is a token
identifying the network address family. The length of an address and
-the meanings of the subsequent words depend on the address family.
+the meanings of the subsequent tokens depend on the address family.
Address family tokens are not case-sensitive on input; on output, they
are always in upper-case.
.PP
does not block the main server, but will block the requesting client,
unless the command is run in the background.
.PP
-If, on input, no recognised address family token is found, the following
-words are assumed to represent an
+If, on input, no recognized address family token is found, the following
+tokens are assumed to represent an
.B INET
address. Addresses output by the server always have an address family
token.
.BR SERVINFO )
produce output in the form of
.IB key = value
-pairs, one per word. Neither the
+pairs, one per token. Neither the
.I key
nor the
.I value
option on the command line). The
.I address
is the network address (see above for the format) at which the peer can
-be contacted. The following options are recognised.
+be contacted. The following options are recognized.
.RS
.\"+opts
.TP
for days, hours, minutes, or seconds respectively; if no suffix is
given, seconds are assumed.
.TP
+.BI "\-key " tag
+Use the public key
+.I tag
+to authenticate the peer. The default is to use the key tagged
+.IR peer .
+.TP
+.B "\-mobile"
+The peer is a mobile device, and is likely to change address rapidly.
+If a packet arrives from an unknown address, the server's usual response
+is to log a warning and discard it. If the server knows of any mobile
+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.
+.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
line reporting the IP address and port number stored for
.IR peer .
.SP
+.BI "ALGS \fR[" peer \fR]
+Emits information about the cryptographic algorithms in use, in
+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
+.B ec
+or
+.BR prime .
+.TP
+.B kx-group-order-bits
+Length of the group order, in bits. This gives an approximate measure
+of the group strength.
+.TP
+.B kx-group-elt-bits
+Length of a group element, in bits. This may be useful when analyzing
+protocol traces.
+.TP
+.B hash
+The hash function in use, e.g.,
+.BR sha256 .
+.TP
+.B mgf
+The mask-generating function in use, e.g.,
+.BR whirlpool-mgf .
+.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 .
+.TP
+.B cipher-keysz
+The length of key used by the bulk data cipher, in octets.
+.TP
+.B cipher-blksz
+The block size of the bulk data cipher, or zero if it's not based on a
+block cipher.
+.TP
+.B cipher-data-limit
+The maximum amount of data to be encrypted using a single key. (A new
+key exchange is instigated well before the limit is reached, in order to
+allow for a seamless changeover of keys.)
+.TP
+.B mac
+The message authentication algorithm in use, e.g.,
+.BR ripemd160-hmac .
+.TP
+.B mac-keysz
+The length of the key used by the message authentication algorithm, in
+octets.
+.TP
+.B mac-tagsz
+The length of the message authentication tag, in octets.
+.TP
+.B blkc
+The block cipher in use, e.g.,
+.BR blowfish .
+.TP
+.B blkc-keysz
+The length of key used by the block cipher, in octets.
+.TP
+.B blkc-blksz
+The block size of the block cipher.
+.PP
+The various sizes are useful, for example, when computing the MTU for a
+tunnel interface. If
+.I MTU
+is the MTU of the path to the peer, then the tunnel MTU should be
+.IP
+.I MTU
+\- 29 \-
+.I bulk-overhead
+.PP
+allowing 20 bytes of IP header, 8 bytes of UDP header, a packet type
+octet, and the bulk-crypto transform overhead (which includes the
+sequence number).
+.RE
+.SP
.BI "BGCANCEL " tag
Cancels the background job with the named
.IR tag .
.SP
.B "DAEMON"
Causes the server to disassociate itself from its terminal and become a
-background task. This only works once. A warning is issued.
+background task. This only works once. A notification is issued.
.SP
.BI "EPING \fR[" options "\fR] " peer
Sends an encrypted ping to the peer, and expects an encrypted response.
.B keepalive
The keepalive interval, in seconds, or zero if no keepalives are to be
sent.
+.TP
+.B key
+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, 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
.B "VERSION"
Causes the server to emit an
.B INFO
-line stating its software version, as two words: the server name, and
+line stating its software version, as two tokens: the server name, and
its version string. The server name
.B tripe
is reserved to the Straylight/Edgeware implementation.
(For any command.) The command couldn't be understood: e.g., the number
of arguments was wrong.
.SP
-.BI "bad-time-spec " word
+.BI "bad-time-spec " token
The
-.I word
+.I token
is not a valid time interval specification. Acceptable time
specifications are nonnegative integers followed optionally by
.BR d ,
failed for some reason. A warning should have been emitted explaining
why.
.SP
+.BI "peer-addr-exists " address\fR...
+(For
+.BR ADD .)
+There is already a peer with the given
+.IR address .
+.SP
.BI "peer-exists " peer
(For
.BR ADD .)
.SP
.BI "unknown-command " token
The command
-.B token
-was not recognised.
+.I token
+was not recognized.
+.SP
+.BI "unknown-jobid " jobid
+(For
+.BR SVCOK ,
+.BR SVCFAIL ,
+and
+.BR SVCINFO .)
+The token
+.I jobid
+is not recognized as identifying an outstanding job. It may have just
+been cancelled.
.SP
.BI "unknown-peer " name
(For
has begun or restarted. If key exchange keeps failing, this message
will be repeated periodically.
.SP
+.BI "NEWADDR " peer " " address
+The given mobile
+.IR peer 's
+IP address has been changed to
+.IR address .
+.SP
.BI "NEWIFNAME " peer " " old-name " " new-name
The given
.IR peer 's
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
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
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
An unknown key-exchange message arrived.
.SS "PEER warnings"
These are largely concerned with management of peers and the low-level
-details of the network protocol. The second word is usually the name of
+details of the network protocol. The second token is usually the name of
a peer, or
.RB ` \- '
if none is relevant.
.B QUIT
command.
.SP
+.BI "SERVER quit foreground-eof"
+The server is running in foreground mode (the
+.B \-F
+option), and encountered end-of-file on standard input.
+.SP
.BI "SERVER select-error " ecode " " message
An error occurred in the server's main event loop. This is bad: if it
happens too many times, the server will abort.
that, or a deliberate attempt at a replay.
.SS "TUN warnings"
These concern the workings of the system-specific tunnel driver. The
-second word is the name of the tunnel interface in question, or
+second token is the name of the tunnel interface in question, or
.RB ` \- '
if none.
.SP
.BI "TUN " ifname " " tun-name " read-error " ecode " " message
Reading from the tunnel device failed.
.SP
+.BI "TUN " ifname " " tun-name " write-error " ecode " " message
+Writing from the tunnel device failed.
+.SP
.BI "TUN " ifname " slip bad-escape"
The SLIP driver encountered a escaped byte it wasn't expecting to see.
The erroneous packet will be ignored.
~mdw / tripe / blobdiff