Add notion of `ephemeral' associations and a goodbye protocol.

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

.\" -*-nroff-*-
.\".
.\" Manual for the administration protocol
.\"
.\" (c) 2008 Straylight/Edgeware
.\"
.
.\"----- Licensing notice ---------------------------------------------------
.\"
.\" This file is part of Trivial IP Encryption (TrIPE).
.\"
.\" TrIPE is free software: you can redistribute it and/or modify it under
.\" the terms of the GNU General Public License as published by the Free
.\" Software Foundation; either version 3 of the License, or (at your
.\" option) any later version.
.\"
.\" TrIPE is distributed in the hope that it will be useful, but WITHOUT
.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with TrIPE.  If not, see <https://www.gnu.org/licenses/>.
.
.\"--------------------------------------------------------------------------
.so ../common/defs.man \" @@@PRE@@@
.
.\"--------------------------------------------------------------------------
.TH tripe-admin 5tripe "18 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
.
.\"--------------------------------------------------------------------------
.SH "NAME"
.
tripe-admin \- administrator commands for TrIPE
.
.\"--------------------------------------------------------------------------
.SH "DESCRIPTION"
.
This manual page describes the administration interface provided by the
.BR tripe (8)
daemon.
.PP
The
.BR tripectl (8)
program can be used either interactively or in scripts to communicate
with the server using this interface.  Alternatively, simple custom
clients can be written in scripting languages such as Perl, Python or
Tcl, or more advanced clients such as GUI monitors can be written in C
with little difficulty.
.PP
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 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
lines, followed by either an
.B OK
line or a
.B FAIL
line.  Each
.B INFO
provides information requested in the command.  An
.B OK
response contains no further data.  A
.B FAIL
code is followed by a machine-readable explanation of why the command
failed.
.PP
Simple command processing is strictly synchronous: the server reads a
command, processes it, and responds, before reading the next command.
All commands can be run as simple commands.  Long-running commands
(e.g.,
.B ADD
and
.BR PING )
block the client until they finish, but the rest of the server continues
running.  See
.B "Background commands"
to find out how to issue long-running commands without blocking.
.SS "Asynchronous broadcasts"
There are three types of asynchronous broadcast messages which aren't
associated with any particular command.  Clients can select which
broadcast messages they're interested in using the
.B WATCH
command.
.PP
The
.B WARN
message contains a machine-readable message warning of an error
encountered while processing a command, unexpected or unusual behaviour
by a peer, or a possible attack by an adversary.  Under normal
conditions, the server shouldn't emit any warnings.
.PP
The
.B TRACE
message contains a human-readable tracing message containing diagnostic
information.  Trace messages are controlled using the
.B \-T
command-line option to the server, or the
.B TRACE
administration command (see below).  Support for tracing can be disabled
when the package is being configured, and may not be available in your
version.
.PP
Finally, the
.B NOTE
message is a machine-readable notification about some routine but
interesting event such as creation or destruction of peers.
.SS "Background commands"
Some commands (e.g.,
.B ADD
and
.BR PING )
take a long time to complete.  To prevent these long-running commands
from tying up a server connection, they can be run in the background.
Not all commands can be run like this: the ones that can provide a
.B \-background
option, which must be supplied with a
.IR tag .
.PP
A command may fail before it starts running in the background.  In this
case, the server emits a
.B FAIL
response, as usual.  To indicate that a command has started running in
the background, the server emits a response of the form
.BI "BGDETACH " tag \fR,
where
.I tag
is the value passed to the
.B \-background
option.  From this point on, the server is ready to process more
commands and reply to them.
.PP
Responses to background commands are indicated by a line beginning with
one of the tokens
.BR BGOK ,
.BR BGFAIL ,
or
.BR BGINFO ,
followed by the command tag.  These correspond to the
.BR OK ,
.BR FAIL ,
and
.B INFO
responses for simple commands:
.B BGINFO
indicates information from a background command which has not completed
yet; and
.B BGOK
and
.B BGFAIL
indicates that a background command succeeded or failed, respectively.
.PP
A background command will never issue an
.B OK
or
.B INFO
response: it will always detach and then issue any
.B BGINFO
lines followed by
.B BGOK
response.
.SS "Client-provided services"
.\"* 25 Service-related messages
An administration client can provide services to other clients.
Services are given names and versions.  A client can attempt to
.I claim
a particular service by issuing the
.B SVCCLAIM
command.  This may fail, for example, if some other client already
provides the same or later version of the service.
.PP
Other clients can issue
.I "service commands"
using the
.B "SVCSUBMIT"
command; the service provider is expected to handle these commands and
reply to them.
.PP
There are three important asynchronous messages which will be sent to
service providers.
.SP
.BI "SVCCANCEL " jobid
The named job has been cancelled, either because the issuing client has
disconnected or explicitly cancelled the job using the
.B BGCANCEL
command.
.SP
.BI "SVCCLAIM " service " " version
Another client has claimed a later version of the named
.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
.I jobid
is a simple token consisting of alphanumeric characters which
.B tripe
uses to identify this job.
.PP
The service provider can reply to the job using the commands
.BR SVCINFO ,
.B SVCOK
and
.BR SVCFAIL .
The first of these sends an
.B INFO
response and leaves the job active; the other two send an
.B OK
or
.B FAIL
response respectively, and mark the job as being complete.
.PP
(Since
.B SVCSUBMIT
is a potentially long-running command, it can be run in the background.
This detail is hidden from service providers:
.B tripe
will issue the corresponding
.BR BG ...
responses when appropriate.)
.SS "Network addresses"
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 tokens depend on the address family.
Address family tokens are not case-sensitive on input; on output, they
are always in upper-case.
.PP
At present, only one address family is understood.
.TP
.BI "INET " address " \fR[" port \fR]
An Internet socket, naming an IPv4 address and UDP port.  On output, the
address is always in numeric dotted-quad form, and the port is given as
a plain number.  On input, DNS hostnames and symbolic port names are
permitted; if omitted, the default port 4070 is used.  Name resolution
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 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.
.SS "Key-value output"
Some commands (e.g.,
.B STATS
and
.BR SERVINFO )
produce output in the form of
.IB key = value
pairs, one per token.  Neither the
.I key
nor the
.I value
contain spaces.
.SS "Trace lists"
Commands which enable or disable kinds of output (e.g.,
.B TRACE
and
.BR WATCH )
work in similar ways.  They take a single optional argument, which
consists of a string of letters selecting message types, optionally
interspersed with
.RB ` + '
to enable, or
.RB ` \- '
to disable, the subsequently listed types.
.PP
If the argument is omitted, the available message types are displayed,
one to an
.B INFO
line, in a fixed-column format.  Column zero contains the key letter for
selecting that message type; column one contains either a space or a
.RB ` + '
sign, if the message type is disabled or enabled respectively; and a
textual description of the message type begins at column 3 and continues
to the end of the line.
.PP
Lowercase key letters control individual message types.  Uppercase key
letters control collections of message types.
.
.\"--------------------------------------------------------------------------
.SH "COMMAND REFERENCE"
.
.\"* 10 Commands
The commands provided are:
.SP
.BI "ADD \fR[" options "\fR] " peer " " address "\fR..."
Adds a new peer.  The peer is given the name
.IR peer ;
the peer's public key is assumed to be in the file
.B keyring.pub
(or whatever alternative file was specified in the
.B \-K
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 recognized.
.RS
.\"+opts
.TP
.BI "\-background " tag
Run the command in the background, using the given
.IR tag .
.TP
.B "\-cork"
Don't send an immediate challenge to the peer; instead, wait until it
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
.BR tripe (8)
daemon is shut down, send a
.B bye
packet to the peer so that it forgets about us; 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.
.TP
.BI "\-keepalive " time
Send a no-op packet if we've not sent a packet to the peer in the last
.I time
interval.  This is useful for persuading port-translating firewalls to
believe that the `connection' is still active.  The
.I time
is expressed as a nonnegative integer followed optionally by
.BR d ,
.BR h ,
.BR m ,
or
.BR s
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
.BI "\-knock \fR[" prefix .\fR] tag
Send the string
.RI [ prefix\fB. ] tag
in
.B token-rq
and
.B knock
messages to the peer during key-exchange.  The string as a whole should
name the local machine to the peer, and
.I tag
should name its public key.  When such messages are received from a
currently unknown peer,
.BR tripe (8)
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
.BR \-ephemeral .
.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.  This option implies
.BR \-ephemeral .
.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
.RE
.SP
.BI "ADDR " peer
Emits an
.B INFO
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
.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.
.SP
.B "DAEMON"
Causes the server to disassociate itself from its terminal and become a
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.
This checks that the peer is running (and not being impersonated), and
that it can encrypt and decrypt packets correctly.  Options and
responses are the same as for the
.B PING
command.
.SP
.BI "FORCEKX " peer
Requests the server to begin a new key exchange with
.I peer
immediately.
.SP
.B "GETCHAL"
Requests a challenge.  The challenge is returned in an
.B INFO
line, as a base64-encoded string.  See
.BR CHECKCHAL .
.SP
.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.
.SP
.B "HELP"
Causes the server to emit an
.B INFO
line for each command it supports.  Each line lists the command name,
followed by the names of the arguments.  This may be helpful as a memory
aid for interactive use, or for program clients probing for features.
.SP
.BI "IFNAME " peer
Emits an
.B INFO
line containing the name of the network interface used to collect IP
packets which are to be encrypted and sent to
.IR peer .
Used by configuration scripts so that they can set up routing tables
appropriately after adding new peers.
.SP
.B "JOBS"
Emits an
.B INFO
line giving the tag for each outstanding background job.
.SP
.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.
.SP
.B "LIST"
For each currently-known peer, an
.B INFO
line is written containing the peer's name, as given to
.BR ADD .
.SP
.BI "NOTIFY " tokens\fR...
Issues a
.B USER
notification to all interested administration clients.
.SP
.BI "PEERINFO " peer
Returns information about a peer, in key-value form.  The following keys
are returned.
.RS
.TP
.B tunnel
The tunnel driver used for this peer.
.TP
.B keepalive
The keepalive interval, in seconds, or zero if no keepalives are to be
sent.
.TP
.B knock
If present, the string sent to the peer to set up the association; see
the
.B \-knock
option to
.BR ADD ,
and the
.B KNOCK
notification.
.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.
.TP
.B corked
Either
.B t
or
.B nil
depending on whether or not (respectively) key-exchange is waiting for
the peer to initiate.
.TP
.B mobile
Either
.B t
or
.B nil
depending on whether or not (respectively) the peer is expected to
change its address unpredictably.
.TP
.B ephemeral
Either
.B t
or
.B nil
depending on whether the association with the peer is expected to be
temporary or persistent (respectively).
.RE
.SP
.BI "PING \fR[" options "\fR] " peer
Send a transport-level ping to the peer.  The ping and its response are
not encrypted or authenticated.  This command, possibly in conjunction
with tracing, is useful for ensuring that UDP packets are actually
flowing in both directions.  See also the
.B EPING
command.
.IP
An
.B INFO
line is printed describing the outcome:
.RS
.TP
.BI "ping-ok " millis
A response was received
.I millis
after the ping was sent.
.TP
.BI "ping-timeout"
No response was received within the time allowed.
.TP
.BI "ping-peer-died"
The peer was killed (probably by another admin connection) before a
response was received.
.RE
.IP
Options recognized for this command are:
.RS
.\"+opts
.TP
.BI "\-background " tag
Run the command in the background, using the given
.IR tag .
.TP
.BI "\-timeout " time
Wait for
.I time
seconds before giving up on a response.  The default is 5 seconds.  The
.I time
is expressed as a nonnegative integer followed optionally by
.BR d ,
.BR h ,
.BR m ,
or
.BR s
for days, hours, minutes, or seconds respectively; if no suffix is
given, seconds are assumed.
.\"-opts
.RE
.SP
.B "PORT"
Emits an
.B INFO
line containing just the number of the UDP port used by the
.B tripe
server.  If you've allowed your server to allocate a port dynamically,
this is how to find out which one it chose.
.SP
.B "RELOAD"
Instructs the server to recheck its keyring files.  The server checks
these periodically anyway but it may be necessary to force a recheck,
for example after adding a new peer key.
.SP
.B "QUIT"
Instructs the server to exit immediately.  A warning is sent.
.SP
.B "SERVINFO"
Returns information about the server, in the form of key-value pairs.
The following keys are used.
.RS
.TP
.B implementation
A keyword naming the implementation of the
.BR tripe (8)
server.  The current implementation is called
.BR edgeware-tripe .
.TP
.B version
The server's version number, as reported by
.BR VERSION .
.TP
.B daemon
Either
.B t
or
.BR nil ,
if the server has or hasn't (respectively) become a daemon.
.RE
.SP
.BI "SETIFNAME " peer " " new-name
Informs the server that the
.IR peer 's
tunnel-interface name has been changed to
.IR new-name .
This is useful if firewalling decisions are made based on interface
names: a setup script for a particular peer can change the name, and
then update the server's records so that they're accurate.
.SP
.BI "STATS " peer
Emits a number of
.B INFO
lines, each containing one or more statistics in the form
.IB name = value \fR.
The statistics-gathering is experimental and subject to change.
.SP
.BI "SVCCLAIM " service " " version
Attempts to claim the named
.IR service ,
offering the given
.IR version .
The claim is successful if the service is currently unclaimed, or if
a version earlier than
.I version
is provided; otherwise the command fails with the error
.BR "service-exists" .
.SP
.BI "SVCENSURE " service " \fR[" version \fR]
Ensure that
.I service
is provided, and (if specified) to at least the given
.IR version .
An error is reported if these conditions are not met; otherwise the
command succeeds silently.
.SP
.BI "SVCFAIL " jobid " " tokens \fR...
Send a
.B FAIL
(or
.BR BGFAIL )
response to the service job with the given
.IR jobid ,
passing the
.I tokens
as the reason for failure.  The job is closed.
.SP
.BI "SVCINFO " jobid " " tokens \fR...
Send an
.B INFO
(or
.BR BGINFO )
response to the service job with the given
.IR jobid ,
passing the
.I tokens
as the info message.  The job remains open.
.SP
.B "SVCLIST"
Output a line of the form
.RS
.IP
.B INFO
.I service
.I version
.PP
for each service currently provided.
.RE
.SP
.BI "SVCOK " jobid
Send an
.B OK
(or
.BR BGINFO )
response to the service job with the given
.IR jobid .
The job is closed.
.SP
.BI "SVCQUERY " service
Emits a number of
.B info
lines in key-value format, describing the named
.IR service.
The following keys are used.
.RS
.TP
.B name
The service's name.
.TP
.B version
The service's version string.
.RE
.SP
.BI "SVCRELEASE " service
Announce that the client no longer wishes to provide the named
.IR service .
.SP
.BI "SVCSUBMIT \fR[" options "\fR] " service " " command " " arguments \fR...
Submit a job to the provider of the given
.IR service ,
passing it the named
.I command
and the given
.IR arguments .
The following options are accepted.
.RS
.\"+opts
.TP
.BI "\-background " tag
Run the command in the background, using the given
.IR tag .
.TP
.BI "\-version " version
Ensure that at least the given
.I version
of the service is available before submitting the job.
.RE
.\"-opts
.SP
.BR "TRACE " [\fIoptions\fP]
Selects trace outputs: see
.B "Trace lists"
above.  Message types provided are:
.RS
.PP
Currently, the following tracing options are supported:
.TP
.B t
Tunnel events: reception of packets to be encrypted, and injection of
successfully-decrypted packets.
.TP
.B r
Peer management events: creation and destruction of peer attachments,
and arrival of messages.
.TP
.B a
Administration interface: acceptance of new connections, and handling of
the backgroud name-resolution required by the
.B ADD
command.
.TP
.B s
Handling of symmetric keysets: creation and expiry of keysets, and
encryption and decryption of messages.
.TP
.B x
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
(packet contents)
and
.B c
(crypto details)
outputs provide extra detail for other outputs.  Specifying
.B p
without
.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 .
.RE
.SP
.B "TUNNELS"
For each available tunnel driver, an
.B INFO
line is printed giving its name.
.SP
.B "VERSION"
Causes the server to emit an
.B INFO
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.
.SP
.BR "WATCH " [\fIoptions\fP]
Enables or disables asynchronous broadcasts
.IR "for the current connection only" .
See
.B "Trace lists"
above.  The default watch state for the connection the server opens
automatically on stdin/stdout is to show warnings and trace messages;
other connections show no asynchronous broadcast messages.  (This is
done in order to guarantee that a program reading the server's stdout
does not miss any warnings.)
.RS
.PP
Message types provided are:
.TP
.B t
.B TRACE
messages.
.TP
.B n
.B NOTE
messages.
.TP
.B w
.B WARN
messages.
.TP
.B A
All of the above.
.RE
.SP
.BI "WARN " tokens\fR...
Issues a
.B USER
warning to all interested administration clients.
.
.\"--------------------------------------------------------------------------
.SH "ERROR MESSAGES"
.
.\"* 20 Error messages (FAIL codes)
The following
.B FAIL
(or
.BR BGFAIL )
messages are sent to clients as a result of errors during command
processing.
.SP
.BI "already-daemon"
(For
.BR DAEMON .)
The
.B tripe
server is already running as a daemon.
.SP
.BI "bad-addr-syntax " message
(For commands accepting socket addresses.)  The address couldn't be
understood.
.SP
.BI "bad-base64 " message
(For commands accepting Base64-encoded input.)  The Base64-encoded
string was invalid.
.SP
.BI "bad-syntax " cmd " " message
(For any command.)  The command couldn't be understood: e.g., the number
of arguments was wrong.
.SP
.BI "bad-time-spec " token
The
.I token
is not a valid time interval specification.  Acceptable time
specifications are nonnegative integers followed optionally by
.BR d ,
.BR h ,
.BR m ,
or
.BR s ,
for days, hours, minutes, or seconds, respectively.
.SP
.BI "bad-trace-option " char
(For
.BR TRACE .)
An unknown trace option was requested.
.SP
.BI "bad-watch-option " char
(For
.BR WATCH .)
An unknown watch option was requested.
.SP
.BI "daemon-error " ecode " " message
(For
.BR DAEMON .)
An error occurred during the attempt to become a daemon, as reported by
.IR message .
.SP
.BI "invalid-port " number
(For
.BR ADD .)
The given port number is out of range.
.SP
.BI "not-service-provider " service
(For
.BR SVCRELEASE .)
The invoking client is not the current provider of the named
.IR service ,
and is therefore not allowed to release it.
.SP
.BI "peer-create-fail " peer
(For
.BR ADD .)
Adding
.I peer
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 .)
There is already a peer named
.IR peer .
.SP
.B "ping-send-failed"
The attempt to send a ping packet failed, probably due to lack of
encryption keys.
.SP
.B "provider-failed"
(For
.BR SVCSUBMIT .)
The service provider disconnected without sending back a final reply to
the job.
.SP
.B "provider-overloaded"
(For
.BR SVCSUBMIT .)
The service provider has too many jobs queued up for it already.
.SP
.BI "resolve-error " hostname
(For
.BR ADD .)
The DNS name
.I hostname
could not be resolved.
.SP
.BI "resolver-timeout " hostname
(For
.BR ADD .)
The DNS name
.I hostname
took too long to resolve.
.SP
.BI "service-exists " service " " version
(For
.BR SVCCLAIM .)
Another client is already providing the stated
.I version
of the
.IR service .
.SP
.BI "service-too-old " service " " version
(For
.B SVCENSURE
and
.BR SVCSUBMIT .)
Only the given
.I version
of the requested
.I service
is available, which does not meet the stated requirements.
.SP
.BI "tag-exists " tag
(For long-running commands.)  The named
.I tag
is already the tag of an outstanding job.
.SP
.BI "unknown-command " token
The command
.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
.BR ADDR ,
.BR IFNAME ,
.BR KILL ,
.BR SETIFNAME ,
and
.BR STATS .)
There is no peer called
.IR name .
.SP
.BI "unknown-port " port
(For
.BR ADD .)
The port name
.I port
couldn't be found in
.BR /etc/services .
.SP
.BI "unknown-service " service
(For
.BR SVCENSURE ,
.BR SVCQUERY ,
.BR SVCRELEASE ,
and
.BR SVCSUBMIT .)
The token
.I service
is not recognized as the name of a client-provided service.
.SP
.BI "unknown-tag " tag
(For
.BR BGCANCEL .)
The given
.I tag
is not the tag for any outstanding background job.  It may have just
finished.
.SP
.BI "unknown-tunnel " tun
(For
.BR ADD .)
The given
.I tun
is not the name of any known tunnel driver.
.
.\"--------------------------------------------------------------------------
.SH "NOTIFICATIONS"
.
.\"* 30 Notification broadcasts (NOTE codes)
The following notifications are sent to clients who request them.
.SP
.BI "ADD " peer " " ifname " " address \fR...
A new peer has been added.  The peer's name is
.IR peer ,
its tunnel is network interface
.IR ifname ,
and its network address is
.IR address .
.SP
.BI "DAEMON"
The server has forked off into the sunset and become a daemon.
.SP
.BI "GREET " challenge " " address \fR...
A valid greeting was received, with the given challenge (exactly as it
was returned by
.B GETCHAL
earlier).
.SP
.BI "KILL " peer
The peer
.I peer
has been killed.
.SP
.BI "KNOCK " peer " " address
The currently unknown
.I peer
is attempting to connect from
.IR address .
.SP
.BI "KXDONE " peer
Key exchange with
.I peer
finished successfully.
.SP
.BI "KXSTART " peer
Key exchange with
.I peer
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
tunnel interface name has been changed from
.I old-name
to
.IR new-name ,
as a result of a
.B SETIFNAME
command.
.SP
.BI "SVCCLAIM " service " " version
The named
.I service
is now available, at the stated
.IR version .
.SP
.BI "SVCRELEASE " service
The named
.I service
is no longer available.
.SP
.BI "USER " tokens\fR...
An administration client issued a notification using the
.B NOTIFY
command.
.
.\"--------------------------------------------------------------------------
.SH "WARNINGS"
.
.\"* 40 Warning broadcasts (WARN codes)
.\"+sep
There are many possible warnings.  They are categorized according to
their first tokens.
.PP
Many of these warnings report system errors.  These are reported as a
pair of tokens, described below as
.I ecode
and
.IR message .
The
.I ecode
is a string of the form
.BI E number
giving the
.BR errno (3)
value of the error; the
.I message
is the `human-readable' form of the message, as reported by
.BR strerror (3).
.SS "ABORT warnings"
These all indicate that the
.B tripe
server has become unable to continue.  If enabled, the server will dump
core in its configuration directory.
.SP
.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.
.SS "ADMIN warnings"
These indicate a problem with the administration socket interface.
.SP
.BI "ADMIN accept-error " ecode " " message
There was an error while attempting to accept a connection from a new
client.
.SP
.BI "ADMIN client-write-error " ecode " " 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.
.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.
.SP
.B "CHAL incorrect-tag"
Challenge received contained the wrong authentication data.  It might be
very stale, or a forgery.
.SP
.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.
.SP
.B "CHAL replay duplicated-sequence"
Challenge received was a definite replay of an old challenge.  Someone's
up to something!
.SP
.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.  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 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.
.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 " unknown-serialization-format " ser
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.
.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 " 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 " which "-keyring " file " key-not-found " tag
A key named
.I tag
couldn't be found in the keyring.
.SP
.BI "KEYMGMT " which "-keyring " file " unknown-key-id 0x" keyid
A key with the given
.I keyid
(in hex) was requested but not found.
.SP
.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
in progress.  All name a
.I peer
as the second token: this is the peer the packet is apparently from,
though it may have been sent by an attacker instead.
.PP
In the descriptions below,
.I msgtoken
is one of the tokens
.BR pre-challenge ,
.BR cookie ,
.BR challenge ,
.BR reply ,
.BR switch-rq ,
.BR switch-ok .
.BR token-rq ,
.BR token ,
or
.BR knock .
.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
uses in its protocol contain a check value which proves that the
challenge is honest.  This message indicates that the check value
supplied is wrong: someone is attempting to use bogus challenges to
persuade your
.B tripe
server to leak private key information.  No chance!
.SP
.BI "KX " peer " decrypt-failed reply\fR|\fBswitch-ok"
A symmetrically-encrypted portion of a key-exchange message failed to
decrypt.
.SP
.BI "KX " peer " invalid " msgtoken
A key-exchange message was malformed.  This almost certainly indicates a
bug somewhere.
.SP
.BI "KX " peer " incorrect cookie\fR|\fBswitch-rq\fR|\fBswitch-ok"
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 " " 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
to flood us with key-exchange messages and make us waste CPU on doing
hard asymmetric crypto sums.
.SP
.BI "KX " peer " unexpected " msgtoken
The message received wasn't appropriate for this stage of the key
exchange process.  This may mean that one of our previous packets got
lost.  For
.BR pre-challenge ,
it may simply mean that the peer has recently restarted.
.SP
.BI "KX " peer " unknown-challenge"
The peer is asking for an answer to a challenge which we don't know
about.  This may mean that we've been inundated with challenges from
some malicious source
.I who can read our messages
and discarded the valid one.
.SP
.BI "KX " peer " unknown-message 0x" nn
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 token is usually the name of
a peer, or
.RB ` \- '
if none is relevant.
.SP
.BI "PEER " peer " bad-packet no-type"
An empty packet arrived.  This is very strange.
.SP
.BI "PEER " peer " bad-packet unknown-category 0x" nn
The message category
.I nn
(in hex) isn't understood.  Probably a strange random packet from
somewhere; could be an unlikely bug.
.SP
.BI "PEER " peer " bad-packet unknown-type 0x" nn
The message type
.I nn
(in hex) isn't understood.  Probably a strange random packet from
somewhere; could be an unlikely bug.
.SP
.BI "PEER " peer " corrupt-encrypted-ping"
The peer sent a ping response which matches an outstanding ping, but its
payload is wrong.  There's definitely a bug somewhere.
.SP
.BI "PEER " peer " corrupt-transport-ping"
The peer (apparently) sent a ping response which matches an outstanding
ping, but its payload is wrong.  Either there's a bug, or the bad guys
are playing tricks on you.
.SP
.BI "PEER " peer " decrypt-failed"
An encrypted IP packet failed to decrypt.  It may have been mangled in
transit, or may be a very old packet from an expired previous session
key.  There is usually a considerable overlap in the validity periods of
successive session keys, so this shouldn't occur unless the key exchange
takes ages or fails.
.SP
.BI "PEER " peer " malformed-encrypted-ping"
The peer sent a ping response which is hopelessly invalid.  There's
definitely a bug somewhere.
.SP
.BI "PEER " peer " malformed-transport-ping"
The peer (apparently) sent a ping response which is hopelessly invalid.
Either there's a bug, or the bad guys are playing tricks on you.
.SP
.BI "PEER " peer " packet-build-failed"
There wasn't enough space in our buffer to put the packet we wanted to
send.  Shouldn't happen.
.SP
.BI "PEER \- socket-read-error " ecode " " message
An error occurred trying to read an incoming packet.
.SP
.BI "PEER " peer " socket-write-error " ecode " " message
An error occurred attempting to send a network packet.  We lost that
one.
.SP
.BI "PEER " address\fR... " socket-write-error " ecode " " message
An error occurred attempting to send a network packet.  We lost that
one.
.SP
.BI "PEER " peer " unexpected-encrypted-ping 0x" id
The peer sent an encrypted ping response whose id doesn't match any
outstanding ping.  Maybe it was delayed for longer than the server was
willing to wait, or maybe the peer has gone mad.
.SP
.BI "PEER \- unexpected-source " address\fR...
A packet arrived from
.I address
(a network address \(en see above), but no peer is known at that
address.  This may indicate a misconfiguration, or simply be a result of
one end of a connection being set up before the other.
.SP
.BI "PEER " peer " unexpected-transport-ping 0x" id
The peer (apparently) sent a transport ping response whose id doesn't
match any outstanding ping.  Maybe it was delayed for longer than the
server was willing to wait, or maybe the peer has gone mad; or maybe
there are bad people trying to confuse you.
.SS "PRIVSEP warnings"
These indicate problems with the privilege-separation helper process.
(The server tries to drop its privileges when it starts up, leaving a
privileged helper process behind which will create and hand over tunnel
descriptors on request, but hopefully not do anything else especially
dangerous.  Tunnel descriptors are not completely safe, but this is
probably better than nothing.)
.SP
.BI "PRIVSEP child-exited " rc
The helper process exited normally with status
.IR rc .
Status 0 means that it thought the server didn't want it any more; 1
means that it was invoked incorrectly; 127 means that some system call
failed.
.SP
.BI "PRIVSEP child-killed " sig
The helper process was killed by signal number
.IR sig .
.SP
.BI "PRIVSEP child-died " status
The helper process died in some unexpected way;
.I status is the raw status code returned by
.BR waitpid (2),
because the server didn't understand how to decode it.
.SP
.BI "PRIVSEP helper-died"
A tunnel driver requires a tunnel descriptor from the helper, but the
helper isn't running so this won't work.
.SP
.BI "PRIVSEP helper-read-error " ecode " " message
The server failed to read a response from the helper process.
.SP
.BI "PRIVSEP helper-short-read"
The helper process didn't send back enough data, and has likely crashed.
.SP
.BI "PRIVSEP helper-write-error " ecode " " message
The server failed to send a message to the helper process.
.SP
.BI "PRIVSEP no-fd-from-helper"
The helper process sent back a positive response, but didn't include the
requested tunnel descriptor.
.SP
.BI "PRIVSEP unknown-response-code"
The helper process sent back an incomprehensible reply.  It's probably
very confused and may crash.
.SS "SERVER warnings"
These indicate problems concerning the server process as a whole.
.SP
.BI "SERVER ignore signal " name
A signal arrived, but the server ignored it.  Currently this happens for
.B SIGHUP
because that's a popular way of telling daemons to re-read their
configuration files.  Since
.B tripe
re-reads its keyrings automatically and has no other configuration
files, it's not relevant, but it seemed better to ignore the signal than
let the server die.
.SP
.BI "SERVER quit signal " \fR[\fInn\fR|\fIname\fR]
A signal arrived and
.B tripe
is going to quit.
.SP
.BI "SERVER quit admin-request"
A client of the administration interface issued a
.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.
.SP
.BI "SERVER waitpid-error " ecode " " message
The server was informed that one of its child processes had exited, but
couldn't retrieve the child's status.
.SS "SYMM warnings"
These are concerned with the symmetric encryption and decryption
process.
.SP
.BI "SYMM replay old-sequence"
A packet was received with an old sequence number.  It may just have
been delayed or duplicated, or it may have been an attempt at a replay
attack.
.SP
.BI "SYMM replay duplicated-sequence"
A packet was received with a sequence number we've definitely seen
before.  It may be an accidental duplication because the 'net is like
that, or a deliberate attempt at a replay.
.SS "TUN warnings"
These concern the workings of the system-specific tunnel driver.  The
second token is the name of the tunnel interface in question, or
.RB ` \- '
if none.
.SP
.BI "TUN \- bsd no-tunnel-devices"
The driver couldn't find an available tunnel device.  Maybe if you
create some more
.BI /dev/tun nn
files, it will work.
.SP
.BI "TUN \- " tun-name " open-error " device " " ecode " " message
An attempt to open the tunnel device file
.I device
failed.
.SP
.BI "TUN \- linux config-error " ecode " " message
Configuring the Linux TUN/TAP interface failed.
.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.
.SP
.BI "TUN " ifname " slip eof"
The SLIP driver encountered end-of-file on its input descriptor.
Pending data is discarded, and no attempt is made to read any more data
from that interface ever.
.SP
.BI "TUN " ifname " slip escape-end"
The SLIP driver encountered an escaped `end' marker.  This probably
means that someone's been sending it junk.  The erroneous packet is
discarded, and we hope that we've rediscovered synchronization.
.SP
.BI "TUN \- slip fork-error " ecode " " message
The SLIP driver encountered an error forking a child process while
allocating a new dynamic interface.
.SP
.BI "TUN \- slip no-slip-interfaces"
The driver ran out of static SLIP interfaces.  Either preallocate more,
or use dynamic SLIP interface allocation.
.SP
.BI "TUN " ifname " slip overflow"
The SLIP driver gave up reading a packet because it got too large.
.SP
.BI "TUN \- slip pipe-error " ecode " " message
The SLIP driver encountered an error creating pipes while allocating a
new dynamic interface.
.SP
.BI "TUN \- slip read-ifname-failed " ecode " " message
The SLIP driver encountered an error reading the name of a dynamically
allocated interface.  Maybe the allocation script is broken.
.SP
.BI "TUN \- unet config-error " ecode " " message
Configuring the Linux Unet interface failed.  Unet is obsolete and
shouldn't be used any more.
.SP
.BI "TUN \- unet getinfo-error " ecode " " message
Reading information about the Unet interface failed.  Unet is obsolete
and shouldn't be used any more.
.SS "USER warnings"
These are issued by administration clients using the
.B WARN
command.
.SP
.BI "USER " tokens\fR...
An administration client issued a warning.
.\"-sep
.
.\"--------------------------------------------------------------------------
.SH "SUMMARY"
.
.SS "Command responses"
.nf
.BI "BGDETACH " tag
.BI "BGFAIL " tag " " tokens \fR...
.BI "BGINFO " tag " " tokens \fR...
.BI "BGOK " tag
.BI "FAIL " tokens \fR...
.BI "INFO " tokens \fR...
.B OK
.fi
.\"= summary
.
.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
.
.BR tripectl (1),
.BR tripe (8).
.PP
.IR "The Trivial IP Encryption Protocol" .
.
.\"--------------------------------------------------------------------------
.SH "AUTHOR"
.
Mark Wooding, <mdw@distorted.org.uk>
.
.\"----- That's all, folks --------------------------------------------------