3 .\" Manual for the administration protocol
5 .\" (c) 2008 Straylight/Edgeware
8 .\"----- Licensing notice ---------------------------------------------------
10 .\" This file is part of Trivial IP Encryption (TrIPE).
12 .\" TrIPE is free software: you can redistribute it and/or modify it under
13 .\" the terms of the GNU General Public License as published by the Free
14 .\" Software Foundation; either version 3 of the License, or (at your
15 .\" option) any later version.
17 .\" TrIPE is distributed in the hope that it will be useful, but WITHOUT
18 .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
19 .\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
22 .\" You should have received a copy of the GNU General Public License
23 .\" along with TrIPE. If not, see <https://www.gnu.org/licenses/>.
25 .\"--------------------------------------------------------------------------
26 .so ../common/defs.man \" @@@PRE@@@
28 .\"--------------------------------------------------------------------------
29 .TH tripe-admin 5tripe "18 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
31 .\"--------------------------------------------------------------------------
34 tripe-admin \- administrator commands for TrIPE
36 .\"--------------------------------------------------------------------------
39 This manual page describes the administration interface provided by the
45 program can be used either interactively or in scripts to communicate
46 with the server using this interface. Alternatively, simple custom
47 clients can be written in scripting languages such as Perl, Python or
48 Tcl, or more advanced clients such as GUI monitors can be written in C
49 with little difficulty.
51 Administration commands use a textual protocol. Each client command or
52 server response consists of a line of ASCII text terminated by a single
53 linefeed character. No command may be longer than 255 characters.
54 .SS "General structure"
55 Each command or response line consists of a sequence of
56 whitespace-separated tokens. The number and nature of whitespace
57 characters separating two tokens in a client command is not significant;
58 the server always uses a single space character. The first token in a
61 identifying the type of command or response contained. Keywords in
62 client commands are not case-sensitive; the server always uses uppercase
65 In order to allow tokens to contain internal whitespace, a quoting
66 mechanism is provided. Whitespace within matched pairs of quotes \(en
71 \(en is considered to be internal. Any character (other than newline)
72 may be escaped by preceding it with a backslash
74 in particular, this can be used to include quote characters. It is
75 impossible for a token to contain a newline character.
77 On output, the server will use double quotes when necessary.
79 For simple client command, the server responds with zero or more
81 lines, followed by either an
87 provides information requested in the command. An
89 response contains no further data. A
91 code is followed by a machine-readable explanation of why the command
94 Simple command processing is strictly synchronous: the server reads a
95 command, processes it, and responds, before reading the next command.
96 All commands can be run as simple commands. Long-running commands
101 block the client until they finish, but the rest of the server continues
103 .B "Background commands"
104 to find out how to issue long-running commands without blocking.
105 .SS "Asynchronous broadcasts"
106 There are three types of asynchronous broadcast messages which aren't
107 associated with any particular command. Clients can select which
108 broadcast messages they're interested in using the
114 message contains a machine-readable message warning of an error
115 encountered while processing a command, unexpected or unusual behaviour
116 by a peer, or a possible attack by an adversary. Under normal
117 conditions, the server shouldn't emit any warnings.
121 message contains a human-readable tracing message containing diagnostic
122 information. Trace messages are controlled using the
124 command-line option to the server, or the
126 administration command (see below). Support for tracing can be disabled
127 when the package is being configured, and may not be available in your
132 message is a machine-readable notification about some routine but
133 interesting event such as creation or destruction of peers.
134 .SS "Background commands"
139 take a long time to complete. To prevent these long-running commands
140 from tying up a server connection, they can be run in the background.
141 Not all commands can be run like this: the ones that can provide a
143 option, which must be supplied with a
146 A command may fail before it starts running in the background. In this
147 case, the server emits a
149 response, as usual. To indicate that a command has started running in
150 the background, the server emits a response of the form
151 .BI "BGDETACH " tag \fR,
154 is the value passed to the
156 option. From this point on, the server is ready to process more
157 commands and reply to them.
159 Responses to background commands are indicated by a line beginning with
165 followed by the command tag. These correspond to the
170 responses for simple commands:
172 indicates information from a background command which has not completed
177 indicates that a background command succeeded or failed, respectively.
179 A background command will never issue an
183 response: it will always detach and then issue any
188 .SS "Client-provided services"
189 .\"* 25 Service-related messages
190 An administration client can provide services to other clients.
191 Services are given names and versions. A client can attempt to
193 a particular service by issuing the
195 command. This may fail, for example, if some other client already
196 provides the same or later version of the service.
198 Other clients can issue
199 .I "service commands"
202 command; the service provider is expected to handle these commands and
205 There are three important asynchronous messages which will be sent to
208 .BI "SVCCANCEL " jobid
209 The named job has been cancelled, either because the issuing client has
210 disconnected or explicitly cancelled the job using the
214 .BI "SVCCLAIM " service " " version
215 Another client has claimed a later version of the named
217 The recipient is no longer the provider of this service.
219 .BI "SVCJOB " jobid " " service " " command " " args \fR...
220 Announces the arrival of a new job. The
222 is a simple token consisting of alphanumeric characters which
224 uses to identify this job.
226 The service provider can reply to the job using the commands
231 The first of these sends an
233 response and leaves the job active; the other two send an
237 response respectively, and mark the job as being complete.
241 is a potentially long-running command, it can be run in the background.
242 This detail is hidden from service providers:
244 will issue the corresponding
246 responses when appropriate.)
247 .SS "Network addresses"
248 A network address is a sequence of tokens. The first is a token
249 identifying the network address family. The length of an address and
250 the meanings of the subsequent tokens depend on the address family.
251 Address family tokens are not case-sensitive on input; on output, they
252 are always in upper-case.
254 The following address families are recognized.
256 .BI "ANY " address " \fR[" port \fR]
257 An address and port number for any supported address family. On output,
259 never uses this form. On input, the
261 is examined: if it is a numeric address for some recognized address
262 family, then it is interpreted as such; otherwise it is looked up using
263 the DNS (in the background). The background resolver's address-sorting
266 simply takes the first address in the returned list which is of a
267 supported address family. Symbolic port numbers are permitted; if
268 omitted, the default port 4070 is used.
270 .BI "INET " address " \fR[" port \fR]
271 An Internet socket, naming an IPv4 address and UDP port. On output, the
273 is always in numeric dotted-quad form, and the
275 is given as a plain decimal number. On input, DNS hostnames and
276 symbolic port names are permitted; if omitted, the default port 4070 is
279 .BI "INET6 " address " \fR[" port \fR]
280 An Internet socket, naming an IPv6 address and UDP port. On output, the
282 is always in numeric hex-and-colons form, and the
284 is given as a plain decimal number. On input, DNS hostnames and
285 symbolic port names may be permitted, depending on how
287 was compiled; if omitted, the default port 4070 is used.
289 If, on input, no recognized address family token is found, the following
290 tokens are assumed to represent an
292 address. Addresses output by the server always have an address family
293 token, and do not use
296 Name resolution never blocks the main server, but will block the
297 requesting client, unless the command is run in the background.
298 .SS "Key-value output"
303 produce output in the form of
305 pairs, one per token. Neither the
311 Commands which enable or disable kinds of output (e.g.,
315 work in similar ways. They take a single optional argument, which
316 consists of a string of letters selecting message types, optionally
321 to disable, the subsequently listed types.
323 If the argument is omitted, the available message types are displayed,
326 line, in a fixed-column format. Column zero contains the key letter for
327 selecting that message type; column one contains either a space or a
329 sign, if the message type is disabled or enabled respectively; and a
330 textual description of the message type begins at column 3 and continues
331 to the end of the line.
333 Lowercase key letters control individual message types. Uppercase key
334 letters control collections of message types.
336 .\"--------------------------------------------------------------------------
337 .SH "COMMAND REFERENCE"
340 The commands provided are:
342 .BI "ADD \fR[" options "\fR] " peer " " address "\fR..."
343 Adds a new peer. The peer is given the name
345 the peer's public key is assumed to be in the file
347 (or whatever alternative file was specified in the
349 option on the command line). The
351 is the network address (see above for the format) at which the peer can
352 be contacted. The following options are recognized.
356 .BI "\-background " tag
357 Run the command in the background, using the given
361 Don't send an immediate challenge to the peer; instead, wait until it
362 sends us something before responding.
365 The association with the peer is not intended to persist indefinitely.
366 When a peer is killed, or the
368 daemon is shut down, a
370 packet is to the peer(s). If a peer marked as ephemeral sends us a
372 packet then it is killed (but in this case no further
376 packet from a peer which isn't marked as ephemeral leaves the peer alone
377 in the hope that the connection can be reestablished.
379 .BI "\-keepalive " time
380 Send a no-op packet if we've not sent a packet to the peer in the last
382 interval. This is useful for persuading port-translating firewalls to
383 believe that the `connection' is still active. The
385 is expressed as a nonnegative integer followed optionally by
391 for days, hours, minutes, or seconds respectively; if no suffix is
392 given, seconds are assumed.
397 to authenticate the peer. The default is to use the key tagged
400 .BI "\-knock \fR[" prefix .\fR] tag
402 .RI [ prefix\fB. ] tag
407 messages to the peer during key-exchange. The string as a whole should
408 name the local machine to the peer, and
410 should name its public key. When such messages are received from a
411 currently unknown peer,
415 notification stating the peer's (claimed) name and address. The server
416 will already have verified that the sender is using the peer's private
417 key by this point. Prior to version 1.6.0, this option used to imply
421 The peer is a mobile device, and is likely to change address rapidly.
422 If a packet arrives from an unknown address, the server's usual response
423 is to log a warning and discard it. If the server knows of any mobile
424 peers, however, it will attempt to decrypt the packet using their keys,
425 and if one succeeds, the server will update its idea of the peer's
428 notification. Prior to version 1.6.0, this option used to imply
434 to authenticate to the peer. The default is to use the key named in the
436 command-line option, or a key with type
444 .BI "\-tunnel " tunnel
445 Use the named tunnel driver, rather than the default.
452 line reporting the IP address and port number stored for
455 .BI "ALGS \fR[" peer \fR]
456 Emits information about the cryptographic algorithms in use, in
459 is given, then describe the algorithms used in the association with that
460 peer; otherwise describe the default algorithms.
463 The keys are as follows.
466 Type of key-exchange group in use, currently either
471 .B kx-group-order-bits
472 Length of the group order, in bits. This gives an approximate measure
473 of the group strength.
476 Length of a group element, in bits. This may be useful when analyzing
480 The hash function in use, e.g.,
484 The mask-generating function in use, e.g.,
488 The size of the hash function's output, in octets.
491 The name of the bulk-crypto transform.
494 The amount of overhead, in bytes, caused by the crypto transform.
497 The name of the bulk data cipher in use, e.g.,
501 The length of key used by the bulk data cipher, in octets.
504 The block size of the bulk data cipher, or zero if it's not based on a
508 The maximum amount of data to be encrypted using a single key. (A new
509 key exchange is instigated well before the limit is reached, in order to
510 allow for a seamless changeover of keys.)
513 The message authentication algorithm in use, e.g.,
517 The length of the key used by the message authentication algorithm, in
521 The length of the message authentication tag, in octets.
524 The block cipher in use, e.g.,
528 The length of key used by the block cipher, in octets.
531 The block size of the block cipher.
533 The various sizes are useful, for example, when computing the MTU for a
536 is the MTU of the path to the peer, then the tunnel MTU should be
546 = 20 (IPv4) or 40 (IPv6) bytes of IP header, 8 bytes of UDP header, a
547 packet type octet, and the bulk-crypto transform overhead (which
548 includes the sequence number).
552 Cancels the background job with the named
555 .BI "CHECKCHAL " challenge
556 Verifies a challenge as being one earlier issued by
558 and not previously either passed to
560 or in a greeting message.
563 Causes the server to disassociate itself from its terminal and become a
564 background task. This only works once. A notification is issued.
566 .BI "EPING \fR[" options "\fR] " peer
567 Sends an encrypted ping to the peer, and expects an encrypted response.
568 This checks that the peer is running (and not being impersonated), and
569 that it can encrypt and decrypt packets correctly. Options and
570 responses are the same as for the
574 .BI "FORCEKX \fR[" options "\fR] " peer
575 Requests the server to begin a new key exchange with
577 immediately. The following options are recognized.
582 Don't actually start a new key exchange; just quietly mark any previous
583 key exchange as stale so that a fresh attempt from the peer will
584 succeed. This is was introduced for use during testing, but it's also
585 useful when a remote peer has forgotten about us: it would be
586 annoying if, once it's learns about us and tries to reinitiate a key
587 exchange, we ignore it because we think we've already done one recently;
588 on the other hand, forcing a key exchange before the remote peer has
589 been reinformed about us is a waste of packets.
594 Requests a challenge. The challenge is returned in an
596 line, as a base64-encoded string. See
599 .BI "GREET " peer " " challenge
600 Sends a greeting packet containing the
602 (base-64 encoded) to the named
604 The expectation is that this will cause the peer to recognize us and
605 begin a key-exchange.
608 Causes the server to emit an
610 line for each command it supports. Each line lists the command name,
611 followed by the names of the arguments. This may be helpful as a memory
612 aid for interactive use, or for program clients probing for features.
617 line containing the name of the network interface used to collect IP
618 packets which are to be encrypted and sent to
620 Used by configuration scripts so that they can set up routing tables
621 appropriately after adding new peers.
626 line giving the tag for each outstanding background job.
629 Causes the server to forget all about
631 All keys are destroyed, and no more packets are sent. A
633 message is sent to the peer if it's marked as
637 command. The following options are
645 message to an ephemeral peer: just quietly forget about it. This is
646 used during testing, and is not expected to be generally useful.
651 For each currently-known peer, an
653 line is written containing the peer's name, as given to
656 .BI "NOTIFY " tokens\fR...
659 notification to all interested administration clients.
662 Returns information about a peer, in key-value form. The following keys
667 The tunnel driver used for this peer.
670 The keepalive interval, in seconds, or zero if no keepalives are to be
674 If present, the string sent to the peer to set up the association; see
684 The (short) key tag being used for the peer, as passed to the
689 The full key tag of the peer's public key currently being used. This
690 may change during the life of the association.
693 The private key tag being used for the peer, as passed to the
697 command-line option. If neither of these was given explicitly, the
698 private key tag is shown as
700 since there is no fixed tag used under these circumstances.
702 .B current-private-key
703 The full key tag of the private key currently being used for this
704 association. This may change during the life of the association.
711 depending on whether or not (respectively) key-exchange is waiting for
712 the peer to initiate.
719 depending on whether or not (respectively) the peer is expected to
720 change its address unpredictably.
727 depending on whether the association with the peer is expected to be
728 temporary or persistent (respectively).
731 .BI "PING \fR[" options "\fR] " peer
732 Send a transport-level ping to the peer. The ping and its response are
733 not encrypted or authenticated. This command, possibly in conjunction
734 with tracing, is useful for ensuring that UDP packets are actually
735 flowing in both directions. See also the
741 line is printed describing the outcome:
744 .BI "ping-ok " millis
745 A response was received
747 after the ping was sent.
750 No response was received within the time allowed.
753 The peer was killed (probably by another admin connection) before a
754 response was received.
757 Options recognized for this command are:
761 .BI "\-background " tag
762 Run the command in the background, using the given
765 .BI "\-timeout " time
768 seconds before giving up on a response. The default is 5 seconds. The
770 is expressed as a nonnegative integer followed optionally by
776 for days, hours, minutes, or seconds respectively; if no suffix is
777 given, seconds are assumed.
785 line containing just the number of the UDP port used by the
787 server, for the given address
789 (or one chosen arbitrarily if omitted -- though
791 tries to use the same port number consistently so this is not a likely
792 problem in practice). If you've allowed your server to allocate a port
793 dynamically, this is how to find out which one it chose.
796 Instructs the server to recheck its keyring files. The server checks
797 these periodically anyway but it may be necessary to force a recheck,
798 for example after adding a new peer key.
801 Instructs the server to exit immediately. A warning is sent.
804 Returns information about the server, in the form of key-value pairs.
805 The following keys are used.
809 A keyword naming the implementation of the
811 server. The current implementation is called
815 The server's version number, as reported by
823 if the server has or hasn't (respectively) become a daemon.
826 .BI "SETIFNAME " peer " " new-name
827 Informs the server that the
829 tunnel-interface name has been changed to
831 This is useful if firewalling decisions are made based on interface
832 names: a setup script for a particular peer can change the name, and
833 then update the server's records so that they're accurate.
838 lines, each containing one or more statistics in the form
839 .IB name = value \fR.
840 The statistics-gathering is experimental and subject to change.
842 .BI "SVCCLAIM " service " " version
843 Attempts to claim the named
847 The claim is successful if the service is currently unclaimed, or if
848 a version earlier than
850 is provided; otherwise the command fails with the error
851 .BR "service-exists" .
853 .BI "SVCENSURE " service " \fR[" version \fR]
856 is provided, and (if specified) to at least the given
858 An error is reported if these conditions are not met; otherwise the
859 command succeeds silently.
861 .BI "SVCFAIL " jobid " " tokens \fR...
866 response to the service job with the given
870 as the reason for failure. The job is closed.
872 .BI "SVCINFO " jobid " " tokens \fR...
877 response to the service job with the given
881 as the info message. The job remains open.
884 Output a line of the form
891 for each service currently provided.
899 response to the service job with the given
903 .BI "SVCQUERY " service
906 lines in key-value format, describing the named
908 The following keys are used.
915 The service's version string.
918 .BI "SVCRELEASE " service
919 Announce that the client no longer wishes to provide the named
922 .BI "SVCSUBMIT \fR[" options "\fR] " service " " command " " arguments \fR...
923 Submit a job to the provider of the given
929 The following options are accepted.
933 .BI "\-background " tag
934 Run the command in the background, using the given
937 .BI "\-version " version
938 Ensure that at least the given
940 of the service is available before submitting the job.
944 .BR "TRACE " [\fIoptions\fP]
945 Selects trace outputs: see
947 above. Message types provided are:
950 Currently, the following tracing options are supported:
953 Tunnel events: reception of packets to be encrypted, and injection of
954 successfully-decrypted packets.
957 Peer management events: creation and destruction of peer attachments,
958 and arrival of messages.
961 Administration interface: acceptance of new connections, and handling of
962 the backgroud name-resolution required by the
967 Handling of symmetric keysets: creation and expiry of keysets, and
968 encryption and decryption of messages.
971 Key exchange: reception, parsing and emission of key exchange messages.
974 Key management: loading keys and checking for file modifications.
977 Display information about challenge issuing and verification.
980 Display contents of packets sent and received by the tunnel and/or peer
984 Display inputs, outputs and intermediate results of cryptographic
985 operations. This includes plaintext and key material. Use with
997 outputs provide extra detail for other outputs. Specifying
1003 isn't useful; neither is specifying
1014 For each available tunnel driver, an
1016 line is printed giving its name.
1019 Causes the server to emit an
1021 line stating its software version, as two tokens: the server name, and
1022 its version string. The server name
1024 is reserved to the Straylight/Edgeware implementation.
1026 .BR "WATCH " [\fIoptions\fP]
1027 Enables or disables asynchronous broadcasts
1028 .IR "for the current connection only" .
1031 above. The default watch state for the connection the server opens
1032 automatically on stdin/stdout is to show warnings and trace messages;
1033 other connections show no asynchronous broadcast messages. (This is
1034 done in order to guarantee that a program reading the server's stdout
1035 does not miss any warnings.)
1038 Message types provided are:
1056 .BI "WARN " tokens\fR...
1059 warning to all interested administration clients.
1061 .\"--------------------------------------------------------------------------
1062 .SH "ERROR MESSAGES"
1064 .\"* 20 Error messages (FAIL codes)
1069 messages are sent to clients as a result of errors during command
1072 .BI "already-daemon"
1077 server is already running as a daemon.
1079 .BI "bad-addr-syntax " message
1080 (For commands accepting socket addresses.) The address couldn't be
1083 .BI "bad-base64 " message
1084 (For commands accepting Base64-encoded input.) The Base64-encoded
1087 .BI "bad-syntax " cmd " " message
1088 (For any command.) The command couldn't be understood: e.g., the number
1089 of arguments was wrong.
1091 .BI "bad-time-spec " token
1092 (For commands accepting a
1096 is not a valid time interval specification. Acceptable time
1097 specifications are nonnegative integers followed optionally by
1103 for days, hours, minutes, or seconds, respectively.
1105 .BI "bad-trace-option " char
1108 An unknown trace option was requested.
1110 .BI "bad-watch-option " char
1113 An unknown watch option was requested.
1115 .BI "daemon-error " ecode " " message
1118 An error occurred during the attempt to become a daemon, as reported by
1122 below for the meanings of
1127 .BI "disabled-address-family " afam
1134 is supported, but was disabled using command-line arguments.
1136 .BI "invalid-port " number
1139 The given port number is out of range.
1141 .BI "not-service-provider " service
1144 The invoking client is not the current provider of the named
1146 and is therefore not allowed to release it.
1148 .BI "peer-create-fail " peer
1153 failed for some reason. A warning should have been emitted explaining
1156 .BI "peer-addr-exists " address\fR...
1159 There is already a peer with the given
1162 .BI "peer-exists " peer
1165 There is already a peer named
1168 .B "ping-send-failed"
1171 The attempt to send a ping packet failed, probably due to lack of
1174 .B "provider-failed"
1177 The service provider disconnected without sending back a final reply to
1180 .B "provider-overloaded"
1183 The service provider has too many jobs queued up for it already.
1185 .BI "resolve-error " hostname
1190 could not be resolved.
1192 .BI "resolver-timeout " hostname
1197 took too long to resolve.
1199 .BI "service-exists " service " " version
1202 Another client is already providing the stated
1207 .BI "service-too-old " service " " version
1216 is available, which does not meet the stated requirements.
1218 .BI "tag-exists " tag
1219 (For long-running commands.) The named
1221 is already the tag of an outstanding job.
1223 .BI "unknown-address-family " afam
1230 .BI "unknown-command " token
1235 .BI "unknown-jobid " jobid
1243 is not recognized as identifying an outstanding job. It may have just
1246 .BI "unknown-peer " name
1254 There is no peer called
1257 .BI "unknown-port " port
1262 couldn't be found in
1265 .BI "unknown-service " service
1274 is not recognized as the name of a client-provided service.
1276 .BI "unknown-tag " tag
1281 is not the tag for any outstanding background job. It may have just
1284 .BI "unknown-tunnel " tun
1289 is not the name of any known tunnel driver.
1291 .\"--------------------------------------------------------------------------
1294 .\"* 30 Notification broadcasts (NOTE codes)
1295 The following notifications are sent to clients who request them.
1297 .BI "ADD " peer " " ifname " " address \fR...
1298 A new peer has been added. The peer's name is
1300 its tunnel is network interface
1302 and its network address is
1306 The server has forked off into the sunset and become a daemon.
1308 .BI "GREET " challenge " " address \fR...
1309 A valid greeting was received, with the given challenge (exactly as it
1319 .BI "KNOCK " peer " " address
1320 The currently unknown
1322 is attempting to connect from
1328 finished successfully.
1333 has begun or restarted. If key exchange keeps failing, this message
1334 will be repeated periodically.
1336 .BI "NEWADDR " peer " " address
1339 IP address has been changed to
1342 .BI "NEWIFNAME " peer " " old-name " " new-name
1345 tunnel interface name has been changed from
1353 .BI "SVCCLAIM " service " " version
1356 is now available, at the stated
1359 .BI "SVCRELEASE " service
1362 is no longer available.
1364 .BI "USER " tokens\fR...
1365 An administration client issued a notification using the
1370 A who-goes-there message was received from an ephemeral
1372 implying that it has forgotten about us. If a service knows how to
1373 inform the peer of our existence, it should do so. This notification is
1374 not sent for peers which have a
1376 string configured, because the server automatically tries knocking again
1379 .\"--------------------------------------------------------------------------
1382 .\"* 40 Warning broadcasts (WARN codes)
1384 There are many possible warnings. They are categorized according to
1387 Many of these warnings report system errors. These are reported as a
1388 pair of tokens, described below as
1394 is a string of the form
1398 value of the error; the
1400 is the `human-readable' form of the message, as reported by
1402 .SS "ABORT warnings"
1403 These all indicate that the
1405 server has become unable to continue. If enabled, the server will dump
1406 core in its configuration directory.
1408 .BI "ABORT repeated-select-errors"
1409 The main event loop is repeatedly failing. If the server doesn't quit,
1410 it will probably waste all available CPU doing nothing.
1412 .BI "ABORT hash-size-too-large hash " name " size " sz " limit " max
1413 An internal inconsistency: the hash function
1417 hash, but the server has been compiled to assume that no hash function
1421 .SS "ADMIN warnings"
1422 These indicate a problem with the administration socket interface.
1424 .BI "ADMIN accept-error " ecode " " message
1425 There was an error while attempting to accept a connection from a new
1428 .BI "ADMIN client-write-error " ecode " " message
1429 There was an error sending data to a client. The connection to the
1430 client has been closed.
1432 .BI "ADMIN admin-socket " path " already-in-use"
1433 The server failed to create the Unix-domain socket object in the
1434 filesystem, because there's already a socket there, and some other
1435 process is actively listening for incoming connections.
1437 .BI "ADMIN admin-socket " path " bind-failed " ecode " " message
1438 The server failed to create the Unix-domain socket object in the
1439 filesystem for an unusual reason. (The usual reason is
1441 but this is handled specially.)
1443 .BI "ADMIN admin-socket " path " chmod-failed " ecode " " message
1444 The server failed to set the correct permissions of the Unix-domain
1447 .BI "ADMIN admin-socket " path " chown-failed " ecode " " message
1448 The server failed to set the correct ownership of the Unix-domain socket
1451 .BI "ADMIN admin-socket " path " create-failed " ecode " " message
1452 The server failed to create its administration socket. This is usually
1453 because some system resource is unavailable.
1455 .BI "ADMIN admin-socket " path " listen-failed " ecode " " message
1456 The server failed to arrange to receive incoming connections on its
1459 .BI "ADMIN admin-socket " path " name-too-long"
1460 The server can't create its administration socket, because the chosen
1463 is too long. There is, for historical reasons, a rather tight limit on
1464 the length of name permitted for Unix-domain sockets, usually around 108
1467 .BI "ADMIN admin-socket " path " stat-failed " ecode " " message
1468 The server failed to create the Unix-domain socket object in the
1469 filesystem, because there's already something there, but the server
1470 couldn't discover what.
1472 .BI "ADMIN admin-socket " path " too-many-retries"
1473 The server failed to create the Unix-domain socket object in the
1474 filesystem. This error indicates that another process is also
1475 repeatedly trying to create a Unix-domain socket at the same
1477 and then failing to actually listen for connections on it, but the
1478 server always loses the applicable race for some reason. This situation
1479 merits investigation.
1481 .BI "ADMIN adns-init-failed " ecode " " message
1482 The server failed to initialize the ADNS asynchronous DNS-resolution
1485 These indicate errors in challenges, either in the
1487 command or in greeting packets.
1489 .B "CHAL impossible-challenge"
1490 The server hasn't issued any challenges yet. Quite how anyone else
1491 thought they could make one up is hard to imagine.
1493 .B "CHAL incorrect-tag"
1494 Challenge received contained the wrong authentication data. It might be
1495 very stale, or a forgery.
1497 .B "CHAL invalid-challenge"
1498 Challenge received was the wrong length. We might have changed MAC
1499 algorithms since the challenge was issued, or it might just be rubbish.
1501 .B "CHAL replay duplicated-sequence"
1502 Challenge received was a definite replay of an old challenge. Someone's
1505 .B "CHAL replay old-sequence"
1506 Challenge received was old, but maybe not actually a replay. Try again.
1507 .SS "KEYMGMT warnings"
1508 These indicate a problem with the keyring files, or the keys stored in
1509 them. The first token is either
1515 in the descriptions below) indicating which keyring file is problematic,
1516 and the second token is the filename of the keyring. Frequently a key
1517 tag may be given next, preceded by the token
1520 .BI "KEYMGMT public-keyring " file " key " tag " algorithm-mismatch"
1521 A peer's public key doesn't request the same algorithms as our private
1524 .BI "KEYMGMT " which "-keyring " file " key " tag " bad-tag-length " len
1525 The key attributes specify the length of MAC tag as
1527 but this is an invalid value \(en either too large or not a multiple of
1530 .BI "KEYMGMT " which "-keyring " file " key " tag " bad-tag-length-string " str
1531 The key attributes contain
1533 where a MAC tag length was expected. The key was generated wrongly.
1535 .BI "KEYMGMT private-keyring " file " key " tag " incorrect-public-key"
1536 The private key doesn't record the correct corresponding public key.
1538 .BI "KEYMGMT " which "-keyring " file " io-error " ecode " " message
1539 A system error occurred while opening or reading the keyring file.
1541 .BI "KEYMGMT private-keyring " file " key " tag " changed-group"
1542 The private keyring has been changed, but the new private key can't be
1543 used because it uses a different group for Diffie\(enHellman key
1546 .BI "KEYMGMT " which "-keyring " file " key " tag " no-hmac-for-hash " hash
1547 No message authentication code was given explicitly, and there's no
1548 implementation of HMAC for the selected hash function
1551 .BI "KEYMGMT " which "-keyring " file " key " tag " unknown-bulk-transform " bulk
1552 The key specifies the use of an unknown bulk-crypto transform
1554 Maybe the key was generated wrongly, or maybe the version of
1558 .BI "KEYMGMT " which "-keyring " file " key " tag " unknown-cipher " cipher
1559 The key specifies the use of an unknown symmetric encryption algorithm
1561 Maybe the key was generated wrongly, or maybe the version of
1562 Catacomb installed is too old.
1564 .BI "KEYMGMT " which "-keyring " file " key " tag " unknown-group-type " type
1565 The key specifies the use of a Diffie\(enHellman group of an unknown
1567 Maybe the key was generated wrongly, or maybe the version of
1571 .BI "KEYMGMT " which "-keyring " file " key " tag " unknown-hash " hash
1572 The key specifies the use of an unknown hash function
1574 Maybe the key was generated wrongly, or maybe the version of Catacomb
1575 installed is too old.
1577 .BI "KEYMGMT " which "-keyring " file " key " tag " unknown-mac " mac
1578 The key specifies the use of an unknown message authentication code
1580 Maybe the key was generated wrongly, or maybe the version of Catacomb
1581 installed is too old.
1583 .BI "KEYMGMT " which "-keyring " file " key " tag " unknown-mgf-cipher " mgf
1584 The key specifies the use of an unknown symmetric encryption function
1586 for mask generation. Maybe the key was generated wrongly, or maybe the
1587 version of Catacomb installed is too old.
1589 .BI "KEYMGMT " which "-keyring " file " key " tag " unknown-serialization-format " ser
1590 The key specifies the use of an unknown serialization format
1592 for hashing group elements. Maybe the key was generated wrongly, or
1593 maybe the version of
1597 .BI "KEYMGMT " which "-keyring " file " key " tag " unsuitable-aead-cipher " cipher "no-aad"
1598 The key specifies the use of an authenticated encryption scheme
1600 which does not support the processing of additional authenticated data.
1601 The most prominent examples of such schemes are the
1615 bulk transform rather than
1617 for these, or switch to one of the IETF
1618 .IB cipher -poly1305
1621 .BI "KEYMGMT " which "-keyring " file " key " tag " unsuitable-aead-cipher " cipher "nonce-too-small"
1622 The key specifies the use of an authenticated encryption scheme
1624 which doesn't even allow a 5-byte (40-bit) nonce. Catacomb doesn't
1625 implement any such limited AE schemes: you must be doing something
1628 .BI "KEYMGMT " which "-keyring " file " key " tag " unsuitable-aead-cipher " cipher "nonce-too-large"
1629 The key specifies the use of an authenticated encryption scheme
1631 which doesn't support any nonce size smaller than 64 bytes (512 bits).
1632 Catacomb doesn't implement any such extravagant AE schemes: you must be
1633 doing something strange.
1635 .BI "KEYMGMT " which "-keyring " file " key " tag " unsuitable-aead-cipher " cipher "nonempty-ciphertext-for-empty-message"
1636 The key specifies the use of an authenticated encryption scheme
1638 which produces ciphertext output even when given a completely empty
1639 message. Catacomb doesn't implement any such unhelpful AE schemes: you
1640 must be doing something strange.
1642 .BI "KEYMGMT " which "-keyring " file " key " tag " " alg " " name " no-key-size " hashsz
1649 The named algorithm requires more key material than the hash function
1650 can provide. You must change either the hash function, or the cipher or
1653 .BI "KEYMGMT " which "-keyring " file " key " tag " mgf " mgf " restrictive-key-schedule"
1654 The cipher selected for mask-generation is unsuitable because it can't
1655 accept arbitrary-sized keys.
1657 .BI "KEYMGMT " which "-keyring " file " key-not-found " tag
1660 couldn't be found in the keyring.
1662 .BI "KEYMGMT " which "-keyring " file " unknown-key-id 0x" keyid
1663 A key with the given
1665 (in hex) was requested but not found.
1667 .BI "KEYMGMT " which "-keyring " file " line " line " " message
1668 The contents of the keyring file are invalid. There may well be a bug
1673 These indicate problems during key-exchange. Many indicate either a bug
1674 in the server (either yours or the remote one), or some kind of attack
1675 in progress. All name a
1677 as the second token: this is the peer the packet is apparently from,
1678 though it may have been sent by an attacker instead.
1680 In the descriptions below,
1682 is one of the tokens
1694 .BI "KX " peer " algorithms-mismatch local-private-key " privtag " peer-public-key " pubtag
1695 The algorithms specified in the peer's public key
1697 don't match the ones described in the private key
1700 .BI "KX " peer " bad-expected-reply-log"
1703 uses in its protocol contain a check value which proves that the
1704 challenge is honest. This message indicates that the check value
1705 supplied is wrong: someone is attempting to use bogus challenges to
1708 server to leak private key information. No chance!
1710 .BI "KX " peer " decrypt-failed reply\fR|\fBswitch-ok"
1711 A symmetrically-encrypted portion of a key-exchange message failed to
1714 .BI "KX " peer " invalid " msgtoken
1715 A key-exchange message was malformed. This almost certainly indicates a
1718 .BI "KX " peer " incorrect cookie\fR|\fBswitch-rq\fR|\fBswitch-ok"
1719 A message didn't contain the right magic data. This may be a replay of
1720 some old exchange, or random packets being sent in an attempt to waste
1723 .BI "KX " peer " " which "-key-expired"
1724 The local private key or the peer's public key (distinguished by
1726 has expired. Either you or the peer's maintainer should have arranged
1727 for a replacement before now.
1729 .BI "KX " peer " sending-cookie"
1730 We've received too many bogus pre-challenge messages. Someone is trying
1731 to flood us with key-exchange messages and make us waste CPU on doing
1732 hard asymmetric crypto sums.
1734 .BI "KX " peer " unexpected " msgtoken
1735 The message received wasn't appropriate for this stage of the key
1736 exchange process. This may mean that one of our previous packets got
1739 it may simply mean that the peer has recently restarted.
1741 .BI "KX " peer " unknown-challenge"
1742 The peer is asking for an answer to a challenge which we don't know
1743 about. This may mean that we've been inundated with challenges from
1744 some malicious source
1745 .I who can read our messages
1746 and discarded the valid one.
1748 .BI "KX " peer " unknown-message 0x" nn
1749 An unknown key-exchange message arrived.
1751 These are largely concerned with management of peers and the low-level
1752 details of the network protocol. The second token is usually the name of
1755 if none is relevant.
1757 .BI "PEER " peer " bad-packet no-type"
1758 An empty packet arrived. This is very strange.
1760 .BI "PEER " peer " bad-packet unknown-category 0x" nn
1761 The message category
1763 (in hex) isn't understood. Probably a strange random packet from
1764 somewhere; could be an unlikely bug.
1766 .BI "PEER " peer " bad-packet unknown-type 0x" nn
1769 (in hex) isn't understood. Probably a strange random packet from
1770 somewhere; could be an unlikely bug.
1772 .BI "PEER " peer " corrupt-encrypted-ping"
1773 The peer sent a ping response which matches an outstanding ping, but its
1774 payload is wrong. There's definitely a bug somewhere.
1776 .BI "PEER " peer " corrupt-transport-ping"
1777 The peer (apparently) sent a ping response which matches an outstanding
1778 ping, but its payload is wrong. Either there's a bug, or the bad guys
1779 are playing tricks on you.
1781 .BI "PEER " peer " decrypt-failed"
1782 An encrypted IP packet failed to decrypt. It may have been mangled in
1783 transit, or may be a very old packet from an expired previous session
1784 key. There is usually a considerable overlap in the validity periods of
1785 successive session keys, so this shouldn't occur unless the key exchange
1786 takes ages or fails.
1788 .BI "PEER " peer " malformed-encrypted-ping"
1789 The peer sent a ping response which is hopelessly invalid. There's
1790 definitely a bug somewhere.
1792 .BI "PEER " peer " malformed-transport-ping"
1793 The peer (apparently) sent a ping response which is hopelessly invalid.
1794 Either there's a bug, or the bad guys are playing tricks on you.
1796 .BI "PEER " peer " packet-build-failed"
1797 There wasn't enough space in our buffer to put the packet we wanted to
1798 send. Shouldn't happen.
1800 .BI "PEER \- socket-read-error " ecode " " message
1801 An error occurred trying to read an incoming packet.
1803 .BI "PEER " peer " socket-write-error " ecode " " message
1804 An error occurred attempting to send a network packet. We lost that
1807 .BI "PEER " address\fR... " disabled-address-family"
1808 An attempt was made to send a packet to an address for which support was
1809 switched off by command-line options.
1811 .BI "PEER " address\fR... " socket-write-error " ecode " " message
1812 An error occurred attempting to send a network packet. We lost that
1815 .BI "PEER \- udp-socket " address-family " bind-failed " ecode " " message
1816 The server failed to associate a UDP socket with a local address.
1818 .BI "PEER \- udp-socket " address-family " create-failed " ecode " " message
1819 The server failed to create a UDP socket for the
1820 .IR address-family .
1822 .BI "PEER \- udp-socket " address-family " read-local-address-failed " ecode " " message
1823 The server failed to discover the local address for one of its own UDP
1826 .BI "PEER \- udp-socket " address-family " set-buffers-failed " ecode " " message
1827 The server failed to configure appropriate buffer sizes on a UDP socket.
1829 .BI "PEER \- udp-socket INET6 set-v6only-failed " ecode " " message
1830 The server failed to configure an IPv6 socket not to try to collect IPv4
1833 .BI "PEER " peer " unexpected-encrypted-ping 0x" id
1834 The peer sent an encrypted ping response whose id doesn't match any
1835 outstanding ping. Maybe it was delayed for longer than the server was
1836 willing to wait, or maybe the peer has gone mad.
1838 .BI "PEER \- unexpected-source " address\fR...
1839 A packet arrived from
1841 (a network address \(en see above), but no peer is known at that
1842 address. This may indicate a misconfiguration, or simply be a result of
1843 one end of a connection being set up before the other.
1845 .BI "PEER " peer " unexpected-transport-ping 0x" id
1846 The peer (apparently) sent a transport ping response whose id doesn't
1847 match any outstanding ping. Maybe it was delayed for longer than the
1848 server was willing to wait, or maybe the peer has gone mad; or maybe
1849 there are bad people trying to confuse you.
1851 .BI "PEER " peer " unexpected-wgt"
1852 A `who-goes-there' message from received from
1854 but the peer isn't ephemeral.
1856 .BI "PEER " peer " unrecognized-wgt"
1857 A `who-goes-there' message from received from
1859 but it doesn't quote the start of a message which we recently sent to
1861 .SS "PRIVSEP warnings"
1862 These indicate problems with the privilege-separation helper process.
1863 (The server tries to drop its privileges when it starts up, leaving a
1864 privileged helper process behind which will create and hand over tunnel
1865 descriptors on request, but hopefully not do anything else especially
1866 dangerous. Tunnel descriptors are not completely safe, but this is
1867 probably better than nothing.)
1869 .BI "PRIVSEP child-exited " rc
1870 The helper process exited normally with status
1872 Status 0 means that it thought the server didn't want it any more; 1
1873 means that it was invoked incorrectly; 127 means that some system call
1876 .BI "PRIVSEP child-killed " sig
1877 The helper process was killed by signal number
1880 .BI "PRIVSEP child-died " status
1881 The helper process died in some unexpected way;
1882 .I status is the raw status code returned by
1884 because the server didn't understand how to decode it.
1886 .BI "PRIVSEP helper-died"
1887 A tunnel driver requires a tunnel descriptor from the helper, but the
1888 helper isn't running so this won't work.
1890 .BI "PRIVSEP helper-read-error " ecode " " message
1891 The server failed to read a response from the helper process.
1893 .BI "PRIVSEP helper-short-read"
1894 The helper process didn't send back enough data, and has likely crashed.
1896 .BI "PRIVSEP helper-write-error " ecode " " message
1897 The server failed to send a message to the helper process.
1899 .BI "PRIVSEP no-fd-from-helper"
1900 The helper process sent back a positive response, but didn't include the
1901 requested tunnel descriptor.
1903 .BI "PRIVSEP socketpair-create-failed " ecode " " message
1904 The server couldn't create the socketpair it's supposed to use to
1905 communicate with the helper process.
1907 .BI "PRIVSEP unknown-response-code"
1908 The helper process sent back an incomprehensible reply. It's probably
1909 very confused and may crash.
1910 .SS "SERVER warnings"
1911 These indicate problems concerning the server process as a whole.
1913 .BI "SERVER ignore signal " name
1914 A signal arrived, but the server ignored it. Currently this happens for
1916 because that's a popular way of telling daemons to re-read their
1917 configuration files. Since
1919 re-reads its keyrings automatically and has no other configuration
1920 files, it's not relevant, but it seemed better to ignore the signal than
1923 .BI "SERVER quit signal " \fR[\fInn\fR|\fIname\fR]
1924 A signal arrived and
1928 .BI "SERVER quit admin-request"
1929 A client of the administration interface issued a
1933 .BI "SERVER daemon-error " ecode " " message
1934 The server failed to become a daemon during initialization.
1936 .BI "SERVER quit foreground-eof"
1937 The server is running in foreground mode (the
1939 option), and encountered end-of-file on standard input.
1941 .BI "SERVER select-error " ecode " " message
1942 An error occurred in the server's main event loop. This is bad: if it
1943 happens too many times, the server will abort.
1945 .BI "SERVER waitpid-error " ecode " " message
1946 The server was informed that one of its child processes had exited, but
1947 couldn't retrieve the child's status.
1949 These are concerned with the symmetric encryption and decryption
1952 .BI "SYMM replay old-sequence"
1953 A packet was received with an old sequence number. It may just have
1954 been delayed or duplicated, or it may have been an attempt at a replay
1957 .BI "SYMM replay duplicated-sequence"
1958 A packet was received with a sequence number we've definitely seen
1959 before. It may be an accidental duplication because the 'net is like
1960 that, or a deliberate attempt at a replay.
1962 These concern the workings of the system-specific tunnel driver. The
1963 second token is the name of the tunnel interface in question, or
1967 .BI "TUN \- bsd no-tunnel-devices"
1968 The driver couldn't find an available tunnel device. Maybe if you
1971 files, it will work.
1973 .BI "TUN \- " tun-name " open-error " device " " ecode " " message
1974 An attempt to open the tunnel device file
1978 .BI "TUN \- linux config-error " ecode " " message
1979 Configuring the Linux TUN/TAP interface failed.
1981 .BI "TUN " ifname " " tun-name " read-error " ecode " " message
1982 Reading from the tunnel device failed.
1984 .BI "TUN " ifname " " tun-name " write-error " ecode " " message
1985 Writing from the tunnel device failed.
1987 .BI "TUN " ifname " slip bad-escape"
1988 The SLIP driver encountered a escaped byte it wasn't expecting to see.
1989 The erroneous packet will be ignored.
1991 .BI "TUN \- slip bad-interface-list"
1992 The interface list, in the
1994 environment variable, is malformed.
1996 .BI "TUN " ifname " slip eof"
1997 The SLIP driver encountered end-of-file on its input descriptor.
1998 Pending data is discarded, and no attempt is made to read any more data
1999 from that interface ever.
2001 .BI "TUN " ifname " slip escape-end"
2002 The SLIP driver encountered an escaped `end' marker. This probably
2003 means that someone's been sending it junk. The erroneous packet is
2004 discarded, and we hope that we've rediscovered synchronization.
2006 .BI "TUN \- slip fork-error " ecode " " message
2007 The SLIP driver encountered an error forking a child process while
2008 allocating a new dynamic interface.
2010 .BI "TUN \- slip no-slip-interfaces"
2011 The driver ran out of static SLIP interfaces. Either preallocate more,
2012 or use dynamic SLIP interface allocation.
2014 .BI "TUN " ifname " slip overflow"
2015 The SLIP driver gave up reading a packet because it got too large.
2017 .BI "TUN \- slip pipe-error " ecode " " message
2018 The SLIP driver encountered an error creating pipes while allocating a
2019 new dynamic interface.
2021 .BI "TUN \- slip read-ifname-failed " ecode " " message
2022 The SLIP driver encountered an error reading the name of a dynamically
2023 allocated interface. Maybe the allocation script is broken.
2025 .BI "TUN \- unet config-error " ecode " " message
2026 Configuring the Linux Unet interface failed. Unet is obsolete and
2027 shouldn't be used any more.
2029 .BI "TUN \- unet getinfo-error " ecode " " message
2030 Reading information about the Unet interface failed. Unet is obsolete
2031 and shouldn't be used any more.
2033 These are issued by administration clients using the
2037 .BI "USER " tokens\fR...
2038 An administration client issued a warning.
2041 .\"--------------------------------------------------------------------------
2044 .SS "Command responses"
2047 .BI "BGFAIL " tag " " tokens \fR...
2048 .BI "BGINFO " tag " " tokens \fR...
2050 .BI "FAIL " tokens \fR...
2051 .BI "INFO " tokens \fR...
2056 .\"--------------------------------------------------------------------------
2062 .IR "The Trivial IP Encryption Protocol" .
2064 .\"--------------------------------------------------------------------------
2067 Mark Wooding, <mdw@distorted.org.uk>
2069 .\"----- That's all, folks --------------------------------------------------
~mdw / tripe / blob