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
.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
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
+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
line reporting the IP address and port number stored for
.IR peer .
.SP
+.B "ALGS"
+Emits information about the cryptographic algorithms in use, in
+key-value form. The keys are as follows.
+.RS
+.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 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.
+.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
+\- 33 \-
+.I cipher-blksz
+\-
+.I mac-tagsz
+.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.
+.RE
+.SP
.BI "BGCANCEL " tag
Cancels the background job with the named
.IR tag .
.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 ,
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
~mdw / tripe / blobdiff