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 At present, only one address family is understood.
256 .BI "INET " address " \fR[" port \fR]
257 An Internet socket, naming an IPv4 address and UDP port. On output, the
258 address is always in numeric dotted-quad form, and the port is given as
259 a plain number. On input, DNS hostnames and symbolic port names are
260 permitted; if omitted, the default port 4070 is used. Name resolution
261 does not block the main server, but will block the requesting client,
262 unless the command is run in the background.
264 If, on input, no recognized address family token is found, the following
265 tokens are assumed to represent an
267 address. Addresses output by the server always have an address family
269 .SS "Key-value output"
274 produce output in the form of
276 pairs, one per token. Neither the
282 Commands which enable or disable kinds of output (e.g.,
286 work in similar ways. They take a single optional argument, which
287 consists of a string of letters selecting message types, optionally
292 to disable, the subsequently listed types.
294 If the argument is omitted, the available message types are displayed,
297 line, in a fixed-column format. Column zero contains the key letter for
298 selecting that message type; column one contains either a space or a
300 sign, if the message type is disabled or enabled respectively; and a
301 textual description of the message type begins at column 3 and continues
302 to the end of the line.
304 Lowercase key letters control individual message types. Uppercase key
305 letters control collections of message types.
307 .\"--------------------------------------------------------------------------
308 .SH "COMMAND REFERENCE"
311 The commands provided are:
313 .BI "ADD \fR[" options "\fR] " peer " " address "\fR..."
314 Adds a new peer. The peer is given the name
316 the peer's public key is assumed to be in the file
318 (or whatever alternative file was specified in the
320 option on the command line). The
322 is the network address (see above for the format) at which the peer can
323 be contacted. The following options are recognized.
327 .BI "\-background " tag
328 Run the command in the background, using the given
332 Don't send an immediate challenge to the peer; instead, wait until it
333 sends us something before responding.
335 .BI "\-keepalive " time
336 Send a no-op packet if we've not sent a packet to the peer in the last
338 interval. This is useful for persuading port-translating firewalls to
339 believe that the `connection' is still active. The
341 is expressed as a nonnegative integer followed optionally by
347 for days, hours, minutes, or seconds respectively; if no suffix is
348 given, seconds are assumed.
353 to authenticate the peer. The default is to use the key tagged
357 The peer is a mobile device, and is likely to change address rapidly.
358 If a packet arrives from an unknown address, the server's usual response
359 is to log a warning and discard it. If the server knows of any mobile
360 peers, however, it will attempt to decrypt the packet using their keys,
361 and if one succeeds, the server will update its idea of the peer's
369 to authenticate to the peer. The default is to use the key named in the
371 command-line option, or a key with type
379 .BI "\-tunnel " tunnel
380 Use the named tunnel driver, rather than the default.
387 line reporting the IP address and port number stored for
390 .BI "ALGS \fR[" peer \fR]
391 Emits information about the cryptographic algorithms in use, in
394 is given, then describe the algorithms used in the association with that
395 peer; otherwise describe the default algorithms.
398 The keys are as follows.
401 Type of key-exchange group in use, currently either
406 .B kx-group-order-bits
407 Length of the group order, in bits. This gives an approximate measure
408 of the group strength.
411 Length of a group element, in bits. This may be useful when analyzing
415 The hash function in use, e.g.,
419 The mask-generating function in use, e.g.,
423 The size of the hash function's output, in octets.
426 The name of the bulk-crypto transform.
429 The amount of overhead, in bytes, caused by the crypto transform.
432 The name of the bulk data cipher in use, e.g.,
436 The length of key used by the bulk data cipher, in octets.
439 The block size of the bulk data cipher, or zero if it's not based on a
443 The maximum amount of data to be encrypted using a single key. (A new
444 key exchange is instigated well before the limit is reached, in order to
445 allow for a seamless changeover of keys.)
448 The message authentication algorithm in use, e.g.,
452 The length of the key used by the message authentication algorithm, in
456 The length of the message authentication tag, in octets.
459 The block cipher in use, e.g.,
463 The length of key used by the block cipher, in octets.
466 The block size of the block cipher.
468 The various sizes are useful, for example, when computing the MTU for a
471 is the MTU of the path to the peer, then the tunnel MTU should be
477 allowing 20 bytes of IP header, 8 bytes of UDP header, a packet type
478 octet, and the bulk-crypto transform overhead (which includes the
483 Cancels the background job with the named
486 .BI "CHECKCHAL " challenge
487 Verifies a challenge as being one earlier issued by
489 and not previously either passed to
491 or in a greeting message.
494 Causes the server to disassociate itself from its terminal and become a
495 background task. This only works once. A notification is issued.
497 .BI "EPING \fR[" options "\fR] " peer
498 Sends an encrypted ping to the peer, and expects an encrypted response.
499 This checks that the peer is running (and not being impersonated), and
500 that it can encrypt and decrypt packets correctly. Options and
501 responses are the same as for the
506 Requests the server to begin a new key exchange with
511 Requests a challenge. The challenge is returned in an
513 line, as a base64-encoded string. See
516 .BI "GREET " peer " " challenge
517 Sends a greeting packet containing the
519 (base-64 encoded) to the named
521 The expectation is that this will cause the peer to recognize us and
522 begin a key-exchange.
525 Causes the server to emit an
527 line for each command it supports. Each line lists the command name,
528 followed by the names of the arguments. This may be helpful as a memory
529 aid for interactive use, or for program clients probing for features.
534 line containing the name of the network interface used to collect IP
535 packets which are to be encrypted and sent to
537 Used by configuration scripts so that they can set up routing tables
538 appropriately after adding new peers.
543 line giving the tag for each outstanding background job.
546 Causes the server to forget all about
548 All keys are destroyed, and no more packets are sent. No notification
549 is sent to the peer: if it's important that the peer be notified, you
550 must think of a way to do that yourself.
553 For each currently-known peer, an
555 line is written containing the peer's name, as given to
558 .BI "NOTIFY " tokens\fR...
561 notification to all interested administration clients.
564 Returns information about a peer, in key-value form. The following keys
569 The tunnel driver used for this peer.
572 The keepalive interval, in seconds, or zero if no keepalives are to be
576 The (short) key tag being used for the peer, as passed to the
581 The full key tag of the peer's public key currently being used. This
582 may change during the life of the association.
585 The private key tag being used for the peer, as passed to the
589 command-line option. If neither of these was given explicitly, the
590 private key tag is shown as
592 since there is no fixed tag used under these circumstances.
594 .B current-private-key
595 The full key tag of the private key currently being used for this
596 association. This may change during the life of the association.
603 depending on whether or not (respectively) key-exchange is waiting for
604 the peer to initiate.
611 depending on whether or not (respectively) the peer is expected to
612 change its address unpredictably.
615 .BI "PING \fR[" options "\fR] " peer
616 Send a transport-level ping to the peer. The ping and its response are
617 not encrypted or authenticated. This command, possibly in conjunction
618 with tracing, is useful for ensuring that UDP packets are actually
619 flowing in both directions. See also the
625 line is printed describing the outcome:
628 .BI "ping-ok " millis
629 A response was received
631 after the ping was sent.
634 No response was received within the time allowed.
637 The peer was killed (probably by another admin connection) before a
638 response was received.
641 Options recognized for this command are:
645 .BI "\-background " tag
646 Run the command in the background, using the given
649 .BI "\-timeout " time
652 seconds before giving up on a response. The default is 5 seconds. The
654 is expressed as a nonnegative integer followed optionally by
660 for days, hours, minutes, or seconds respectively; if no suffix is
661 given, seconds are assumed.
668 line containing just the number of the UDP port used by the
670 server. If you've allowed your server to allocate a port dynamically,
671 this is how to find out which one it chose.
674 Instructs the server to recheck its keyring files. The server checks
675 these periodically anyway but it may be necessary to force a recheck,
676 for example after adding a new peer key.
679 Instructs the server to exit immediately. A warning is sent.
682 Returns information about the server, in the form of key-value pairs.
683 The following keys are used.
687 A keyword naming the implementation of the
689 server. The current implementation is called
693 The server's version number, as reported by
701 if the server has or hasn't (respectively) become a daemon.
704 .BI "SETIFNAME " peer " " new-name
705 Informs the server that the
707 tunnel-interface name has been changed to
709 This is useful if firewalling decisions are made based on interface
710 names: a setup script for a particular peer can change the name, and
711 then update the server's records so that they're accurate.
716 lines, each containing one or more statistics in the form
717 .IB name = value \fR.
718 The statistics-gathering is experimental and subject to change.
720 .BI "SVCCLAIM " service " " version
721 Attempts to claim the named
725 The claim is successful if the service is currently unclaimed, or if
726 a version earlier than
728 is provided; otherwise the command fails with the error
729 .BR "service-exists" .
731 .BI "SVCENSURE " service " \fR[" version \fR]
734 is provided, and (if specified) to at least the given
736 An error is reported if these conditions are not met; otherwise the
737 command succeeds silently.
739 .BI "SVCFAIL " jobid " " tokens \fR...
744 response to the service job with the given
748 as the reason for failure. The job is closed.
750 .BI "SVCINFO " jobid " " tokens \fR...
755 response to the service job with the given
759 as the info message. The job remains open.
762 Output a line of the form
769 for each service currently provided.
777 response to the service job with the given
781 .BI "SVCQUERY " service
784 lines in key-value format, describing the named
786 The following keys are used.
793 The service's version string.
796 .BI "SVCRELEASE " service
797 Announce that the client no longer wishes to provide the named
800 .BI "SVCSUBMIT \fR[" options "\fR] " service " " command " " arguments \fR...
801 Submit a job to the provider of the given
807 The following options are accepted.
811 .BI "\-background " tag
812 Run the command in the background, using the given
815 .BI "\-version " version
816 Ensure that at least the given
818 of the service is available before submitting the job.
822 .BR "TRACE " [\fIoptions\fP]
823 Selects trace outputs: see
825 above. Message types provided are:
828 Currently, the following tracing options are supported:
831 Tunnel events: reception of packets to be encrypted, and injection of
832 successfully-decrypted packets.
835 Peer management events: creation and destruction of peer attachments,
836 and arrival of messages.
839 Administration interface: acceptance of new connections, and handling of
840 the backgroud name-resolution required by the
845 Handling of symmetric keysets: creation and expiry of keysets, and
846 encryption and decryption of messages.
849 Key exchange: reception, parsing and emission of key exchange messages.
852 Key management: loading keys and checking for file modifications.
855 Display information about challenge issuing and verification.
858 Display contents of packets sent and received by the tunnel and/or peer
862 Display inputs, outputs and intermediate results of cryptographic
863 operations. This includes plaintext and key material. Use with
875 outputs provide extra detail for other outputs. Specifying
881 isn't useful; neither is specifying
892 For each available tunnel driver, an
894 line is printed giving its name.
897 Causes the server to emit an
899 line stating its software version, as two tokens: the server name, and
900 its version string. The server name
902 is reserved to the Straylight/Edgeware implementation.
904 .BR "WATCH " [\fIoptions\fP]
905 Enables or disables asynchronous broadcasts
906 .IR "for the current connection only" .
909 above. The default watch state for the connection the server opens
910 automatically on stdin/stdout is to show warnings and trace messages;
911 other connections show no asynchronous broadcast messages. (This is
912 done in order to guarantee that a program reading the server's stdout
913 does not miss any warnings.)
916 Message types provided are:
934 .BI "WARN " tokens\fR...
937 warning to all interested administration clients.
939 .\"--------------------------------------------------------------------------
942 .\"* 20 Error messages (FAIL codes)
947 messages are sent to clients as a result of errors during command
955 server is already running as a daemon.
957 .BI "bad-addr-syntax " message
958 (For commands accepting socket addresses.) The address couldn't be
961 .BI "bad-base64 " message
962 (For commands accepting Base64-encoded input.) The Base64-encoded
965 .BI "bad-syntax " cmd " " message
966 (For any command.) The command couldn't be understood: e.g., the number
967 of arguments was wrong.
969 .BI "bad-time-spec " token
972 is not a valid time interval specification. Acceptable time
973 specifications are nonnegative integers followed optionally by
979 for days, hours, minutes, or seconds, respectively.
981 .BI "bad-trace-option " char
984 An unknown trace option was requested.
986 .BI "bad-watch-option " char
989 An unknown watch option was requested.
991 .BI "daemon-error " ecode " " message
994 An error occurred during the attempt to become a daemon, as reported by
997 .BI "invalid-port " number
1000 The given port number is out of range.
1002 .BI "not-service-provider " service
1005 The invoking client is not the current provider of the named
1007 and is therefore not allowed to release it.
1009 .BI "peer-create-fail " peer
1014 failed for some reason. A warning should have been emitted explaining
1017 .BI "peer-addr-exists " address\fR...
1020 There is already a peer with the given
1023 .BI "peer-exists " peer
1026 There is already a peer named
1029 .B "ping-send-failed"
1030 The attempt to send a ping packet failed, probably due to lack of
1033 .B "provider-failed"
1036 The service provider disconnected without sending back a final reply to
1039 .B "provider-overloaded"
1042 The service provider has too many jobs queued up for it already.
1044 .BI "resolve-error " hostname
1049 could not be resolved.
1051 .BI "resolver-timeout " hostname
1056 took too long to resolve.
1058 .BI "service-exists " service " " version
1061 Another client is already providing the stated
1066 .BI "service-too-old " service " " version
1075 is available, which does not meet the stated requirements.
1077 .BI "tag-exists " tag
1078 (For long-running commands.) The named
1080 is already the tag of an outstanding job.
1082 .BI "unknown-command " token
1087 .BI "unknown-jobid " jobid
1095 is not recognized as identifying an outstanding job. It may have just
1098 .BI "unknown-peer " name
1106 There is no peer called
1109 .BI "unknown-port " port
1114 couldn't be found in
1117 .BI "unknown-service " service
1126 is not recognized as the name of a client-provided service.
1128 .BI "unknown-tag " tag
1133 is not the tag for any outstanding background job. It may have just
1136 .BI "unknown-tunnel " tun
1141 is not the name of any known tunnel driver.
1143 .\"--------------------------------------------------------------------------
1146 .\"* 30 Notification broadcasts (NOTE codes)
1147 The following notifications are sent to clients who request them.
1149 .BI "ADD " peer " " ifname " " address \fR...
1150 A new peer has been added. The peer's name is
1152 its tunnel is network interface
1154 and its network address is
1158 The server has forked off into the sunset and become a daemon.
1160 .BI "GREET " challenge " " address \fR...
1161 A valid greeting was received, with the given challenge (exactly as it
1174 finished successfully.
1179 has begun or restarted. If key exchange keeps failing, this message
1180 will be repeated periodically.
1182 .BI "NEWADDR " peer " " address
1185 IP address has been changed to
1188 .BI "NEWIFNAME " peer " " old-name " " new-name
1191 tunnel interface name has been changed from
1199 .BI "SVCCLAIM " service " " version
1202 is now available, at the stated
1205 .BI "SVCRELEASE " service
1208 is no longer available.
1210 .BI "USER " tokens\fR...
1211 An administration client issued a notification using the
1215 .\"--------------------------------------------------------------------------
1218 .\"* 40 Warning broadcasts (WARN codes)
1220 There are many possible warnings. They are categorized according to
1223 Many of these warnings report system errors. These are reported as a
1224 pair of tokens, described below as
1230 is a string of the form
1234 value of the error; the
1236 is the `human-readable' form of the message, as reported by
1238 .SS "ABORT warnings"
1239 These all indicate that the
1241 server has become unable to continue. If enabled, the server will dump
1242 core in its configuration directory.
1244 .BI "ABORT repeated-select-errors"
1245 The main event loop is repeatedly failing. If the server doesn't quit,
1246 it will probably waste all available CPU doing nothing.
1247 .SS "ADMIN warnings"
1248 These indicate a problem with the administration socket interface.
1250 .BI "ADMIN accept-error " ecode " " message
1251 There was an error while attempting to accept a connection from a new
1254 .BI "ADMIN client-write-error " ecode " " message
1255 There was an error sending data to a client. The connection to the
1256 client has been closed.
1258 These indicate errors in challenges, either in the
1260 command or in greeting packets.
1262 .B "CHAL impossible-challenge"
1263 The server hasn't issued any challenges yet. Quite how anyone else
1264 thought he could make one up is hard to imagine.
1266 .B "CHAL incorrect-tag"
1267 Challenge received contained the wrong authentication data. It might be
1268 very stale, or a forgery.
1270 .B "CHAL invalid-challenge"
1271 Challenge received was the wrong length. We might have changed MAC
1272 algorithms since the challenge was issued, or it might just be rubbish.
1274 .B "CHAL replay duplicated-sequence"
1275 Challenge received was a definite replay of an old challenge. Someone's
1278 .B "CHAL replay old-sequence"
1279 Challenge received was old, but maybe not actually a replay. Try again.
1280 .SS "KEYMGMT warnings"
1281 These indicate a problem with the keyring files, or the keys stored in
1282 them. The first token is either
1288 in the descriptions below) indicating which keyring file is problematic,
1289 and the second token is the filename of the keyring. Frequently a key
1290 tag may be given next, preceded by the token
1293 .BI "KEYMGMT private-keyring " file " key " tag " incorrect-public-key"
1294 The private key doesn't record the correct corresponding public key.
1296 .BI "KEYMGMT public-keyring " file " key " tag " algorithm-mismatch"
1297 A peer's public key doesn't request the same algorithms as our private
1300 .BI "KEYMGMT " which "-keyring " file " key " tag " bad-tag-length " len
1301 The key attributes specify the length of MAC tag as
1303 but this is an invalid value \(en either too large or not a multiple of
1306 .BI "KEYMGMT " which "-keyring " file " key " tag " bad-tag-length-string " str
1307 The key attributes contain
1309 where a MAC tag length was expected. The key was generated wrongly.
1311 .BI "KEYMGMT private-keyring " file " key " tag " changed-group"
1312 The private keyring has been changed, but the new private key can't be
1313 used because it uses a different group for Diffie\(enHellman key
1316 .BI "KEYMGMT " which "-keyring " file " io-error " ecode " " message
1317 A system error occurred while opening or reading the keyring file.
1319 .BI "KEYMGMT " which "-keyring " file " key " tag " unknown-bulk-transform " bulk
1320 The key specifies the use of an unknown bulk-crypto transform
1322 Maybe the key was generated wrongly, or maybe the version of Catacomb
1323 installed is too old.
1325 .BI "KEYMGMT " which "-keyring " file " key " tag " unknown-cipher " cipher
1326 The key specifies the use of an unknown symmetric encryption algorithm
1328 Maybe the key was generated wrongly, or maybe the version of
1329 Catacomb installed is too old.
1331 .BI "KEYMGMT " which "-keyring " file " key " tag " unknown-group-type " type
1332 The key specifies the use of a Diffie\(enHellman group of an unknown
1334 Maybe the key was generated wrongly, or maybe the version of
1338 .BI "KEYMGMT " which "-keyring " file " key " tag " unknown-hash " hash
1339 The key specifies the use of an unknown hash function
1341 Maybe the key was generated wrongly, or maybe the version of Catacomb
1342 installed is too old.
1344 .BI "KEYMGMT " which "-keyring " file " key " tag " unknown-mac " mac
1345 The key specifies the use of an unknown message authentication code
1347 Maybe the key was generated wrongly, or maybe the version of Catacomb
1348 installed is too old.
1350 .BI "KEYMGMT " which "-keyring " file " key " tag " unknown-mgf-cipher " mgf
1351 The key specifies the use of an unknown symmetric encryption function
1353 for mask generation. Maybe the key was generated wrongly, or maybe the
1354 version of Catacomb installed is too old.
1356 .BI "KEYMGMT " which "-keyring " file " key " tag " unknown-serialization-format " ser
1357 The key specifies the use of an unknown serialization format
1359 for hashing group elements. Maybe the key was generated wrongly, or
1360 maybe the version of Catacomb installed is too old.
1362 .BI "KEYMGMT " which "-keyring " file " key " tag " no-hmac-for-hash " hash
1363 No message authentication code was given explicitly, and there's no
1364 implementation of HMAC for the selected hash function
1367 .BI "KEYMGMT " which "-keyring " file " key " tag " " alg " " name " no-key-size " hashsz
1374 The named algorithm requires more key material than the hash function
1375 can provide. You must change either the hash function, or the cipher or
1378 .BI "KEYMGMT " which "-keyring " file " key " tag " mgf " mgf " restrictive-key-schedule"
1379 The cipher selected for mask-generation is unsuitable because it can't
1380 accept arbitrary-sized keys.
1382 .BI "KEYMGMT " which "-keyring " file " key-not-found " tag
1385 couldn't be found in the keyring.
1387 .BI "KEYMGMT " which "-keyring " file " line " line " " message
1388 The contents of the keyring file are invalid. There may well be a bug
1393 These indicate problems during key-exchange. Many indicate either a bug
1394 in the server (either yours or the remote one), or some kind of attack
1395 in progress. All name a
1397 as the second token: this is the peer the packet is apparently from,
1398 though it may have been sent by an attacker instead.
1400 In the descriptions below,
1402 is one of the tokens
1411 .BI "KX " peer " algorithms-mismatch local-private-key " privtag " peer-public-key " pubtag
1412 The algorithms specified in the peer's public key
1414 don't match the ones described in the private key
1417 .BI "KX " peer " bad-expected-reply-log"
1420 uses in its protocol contain a check value which proves that the
1421 challenge is honest. This message indicates that the check value
1422 supplied is wrong: someone is attempting to use bogus challenges to
1425 server to leak private key information. No chance!
1427 .BI "KX " peer " decrypt-failed reply\fR|\fBswitch-ok"
1428 A symmetrically-encrypted portion of a key-exchange message failed to
1431 .BI "KX " peer " invalid " msgtoken
1432 A key-exchange message was malformed. This almost certainly indicates a
1435 .BI "KX " peer " incorrect cookie\fR|\fBswitch-rq\fR|\fBswitch-ok"
1436 A message didn't contain the right magic data. This may be a replay of
1437 some old exchange, or random packets being sent in an attempt to waste
1440 .BI "KX " peer " " which "-key-expired"
1441 The local private key or the peer's public key (distinguished by
1443 has expired. Either you or the peer's maintainer should have arranged
1444 for a replacement before now.
1446 .BI "KX " peer " sending-cookie"
1447 We've received too many bogus pre-challenge messages. Someone is trying
1448 to flood us with key-exchange messages and make us waste CPU on doing
1449 hard asymmetric crypto sums.
1451 .BI "KX " peer " unexpected " msgtoken
1452 The message received wasn't appropriate for this stage of the key
1453 exchange process. This may mean that one of our previous packets got
1456 it may simply mean that the peer has recently restarted.
1458 .BI "KX " peer " unknown-challenge"
1459 The peer is asking for an answer to a challenge which we don't know
1460 about. This may mean that we've been inundated with challenges from
1461 some malicious source
1462 .I who can read our messages
1463 and discarded the valid one.
1465 .BI "KX " peer " unknown-message 0x" nn
1466 An unknown key-exchange message arrived.
1468 These are largely concerned with management of peers and the low-level
1469 details of the network protocol. The second token is usually the name of
1472 if none is relevant.
1474 .BI "PEER " peer " bad-packet no-type"
1475 An empty packet arrived. This is very strange.
1477 .BI "PEER " peer " bad-packet unknown-category 0x" nn
1478 The message category
1480 (in hex) isn't understood. Probably a strange random packet from
1481 somewhere; could be an unlikely bug.
1483 .BI "PEER " peer " bad-packet unknown-type 0x" nn
1486 (in hex) isn't understood. Probably a strange random packet from
1487 somewhere; could be an unlikely bug.
1489 .BI "PEER " peer " corrupt-encrypted-ping"
1490 The peer sent a ping response which matches an outstanding ping, but its
1491 payload is wrong. There's definitely a bug somewhere.
1493 .BI "PEER " peer " corrupt-transport-ping"
1494 The peer (apparently) sent a ping response which matches an outstanding
1495 ping, but its payload is wrong. Either there's a bug, or the bad guys
1496 are playing tricks on you.
1498 .BI "PEER " peer " decrypt-failed"
1499 An encrypted IP packet failed to decrypt. It may have been mangled in
1500 transit, or may be a very old packet from an expired previous session
1501 key. There is usually a considerable overlap in the validity periods of
1502 successive session keys, so this shouldn't occur unless the key exchange
1503 takes ages or fails.
1505 .BI "PEER " peer " malformed-encrypted-ping"
1506 The peer sent a ping response which is hopelessly invalid. There's
1507 definitely a bug somewhere.
1509 .BI "PEER " peer " malformed-transport-ping"
1510 The peer (apparently) sent a ping response which is hopelessly invalid.
1511 Either there's a bug, or the bad guys are playing tricks on you.
1513 .BI "PEER " peer " packet-build-failed"
1514 There wasn't enough space in our buffer to put the packet we wanted to
1515 send. Shouldn't happen.
1517 .BI "PEER \- socket-read-error " ecode " " message
1518 An error occurred trying to read an incoming packet.
1520 .BI "PEER " peer " socket-write-error " ecode " " message
1521 An error occurred attempting to send a network packet. We lost that
1524 .BI "PEER " peer " unexpected-encrypted-ping 0x" id
1525 The peer sent an encrypted ping response whose id doesn't match any
1526 outstanding ping. Maybe it was delayed for longer than the server was
1527 willing to wait, or maybe the peer has gone mad.
1529 .BI "PEER \- unexpected-source " address\fR...
1530 A packet arrived from
1532 (a network address \(en see above), but no peer is known at that
1533 address. This may indicate a misconfiguration, or simply be a result of
1534 one end of a connection being set up before the other.
1536 .BI "PEER " peer " unexpected-transport-ping 0x" id
1537 The peer (apparently) sent a transport ping response whose id doesn't
1538 match any outstanding ping. Maybe it was delayed for longer than the
1539 server was willing to wait, or maybe the peer has gone mad; or maybe
1540 there are bad people trying to confuse you.
1541 .SS "SERVER warnings"
1542 These indicate problems concerning the server process as a whole.
1544 .BI "SERVER ignore signal " name
1545 A signal arrived, but the server ignored it. Currently this happens for
1547 because that's a popular way of telling daemons to re-read their
1548 configuration files. Since
1550 re-reads its keyrings automatically and has no other configuration
1551 files, it's not relevant, but it seemed better to ignore the signal than
1554 .BI "SERVER quit signal " \fR[\fInn\fR|\fIname\fR]
1555 A signal arrived and
1559 .BI "SERVER quit admin-request"
1560 A client of the administration interface issued a
1564 .BI "SERVER quit foreground-eof"
1565 The server is running in foreground mode (the
1567 option), and encountered end-of-file on standard input.
1569 .BI "SERVER select-error " ecode " " message
1570 An error occurred in the server's main event loop. This is bad: if it
1571 happens too many times, the server will abort.
1573 These are concerned with the symmetric encryption and decryption
1576 .BI "SYMM replay old-sequence"
1577 A packet was received with an old sequence number. It may just have
1578 been delayed or duplicated, or it may have been an attempt at a replay
1581 .BI "SYMM replay duplicated-sequence"
1582 A packet was received with a sequence number we've definitely seen
1583 before. It may be an accidental duplication because the 'net is like
1584 that, or a deliberate attempt at a replay.
1586 These concern the workings of the system-specific tunnel driver. The
1587 second token is the name of the tunnel interface in question, or
1591 .BI "TUN \- bsd no-tunnel-devices"
1592 The driver couldn't find an available tunnel device. Maybe if you
1595 files, it will work.
1597 .BI "TUN \- " tun-name " open-error " device " " ecode " " message
1598 An attempt to open the tunnel device file
1602 .BI "TUN \- linux config-error " ecode " " message
1603 Configuring the Linux TUN/TAP interface failed.
1605 .BI "TUN " ifname " " tun-name " read-error " ecode " " message
1606 Reading from the tunnel device failed.
1608 .BI "TUN " ifname " " tun-name " write-error " ecode " " message
1609 Writing from the tunnel device failed.
1611 .BI "TUN " ifname " slip bad-escape"
1612 The SLIP driver encountered a escaped byte it wasn't expecting to see.
1613 The erroneous packet will be ignored.
1615 .BI "TUN " ifname " slip eof"
1616 The SLIP driver encountered end-of-file on its input descriptor.
1617 Pending data is discarded, and no attempt is made to read any more data
1618 from that interface ever.
1620 .BI "TUN " ifname " slip escape-end"
1621 The SLIP driver encountered an escaped `end' marker. This probably
1622 means that someone's been sending it junk. The erroneous packet is
1623 discarded, and we hope that we've rediscovered synchronization.
1625 .BI "TUN \- slip fork-error " ecode " " message
1626 The SLIP driver encountered an error forking a child process while
1627 allocating a new dynamic interface.
1629 .BI "TUN \- slip no-slip-interfaces"
1630 The driver ran out of static SLIP interfaces. Either preallocate more,
1631 or use dynamic SLIP interface allocation.
1633 .BI "TUN " ifname " slip overflow"
1634 The SLIP driver gave up reading a packet because it got too large.
1636 .BI "TUN \- slip pipe-error " ecode " " message
1637 The SLIP driver encountered an error creating pipes while allocating a
1638 new dynamic interface.
1640 .BI "TUN \- slip read-ifname-failed " ecode " " message
1641 The SLIP driver encountered an error reading the name of a dynamically
1642 allocated interface. Maybe the allocation script is broken.
1644 .BI "TUN \- unet config-error " ecode " " message
1645 Configuring the Linux Unet interface failed. Unet is obsolete and
1646 shouldn't be used any more.
1648 .BI "TUN \- unet getinfo-error " ecode " " message
1649 Reading information about the Unet interface failed. Unet is obsolete
1650 and shouldn't be used any more.
1652 These are issued by administration clients using the
1656 .BI "USER " tokens\fR...
1657 An administration client issued a warning.
1660 .\"--------------------------------------------------------------------------
1663 .SS "Command responses"
1666 .BI "BGFAIL " tag " " tokens \fR...
1667 .BI "BGINFO " tag " " tokens \fR...
1669 .BI "FAIL " tokens \fR...
1670 .BI "INFO " tokens \fR...
1675 .\"--------------------------------------------------------------------------
1681 .IR "The Trivial IP Encryption Protocol" .
1683 .\"--------------------------------------------------------------------------
1686 Mark Wooding, <mdw@distorted.org.uk>
1688 .\"----- That's all, folks --------------------------------------------------
~mdw / tripe / blob