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
13 .\" it under the terms of the GNU General Public License as published by
14 .\" the Free Software Foundation; either version 2 of the License, or
15 .\" (at your option) any later version.
17 .\" TrIPE is distributed in the hope that it will be useful,
18 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
19 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20 .\" GNU General Public License for more details.
22 .\" You should have received a copy of the GNU General Public License
23 .\" along with TrIPE; if not, write to the Free Software Foundation,
24 .\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
26 .\"--------------------------------------------------------------------------
27 .so ../common/defs.man \" @@@PRE@@@
29 .\"--------------------------------------------------------------------------
30 .TH tripe-admin 5 "18 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
32 .\"--------------------------------------------------------------------------
35 tripe-admin \- administrator commands for TrIPE
37 .\"--------------------------------------------------------------------------
40 This manual page describes the administration interface provided by the
46 program can be used either interactively or in scripts to communicate
47 with the server using this interface. Alternatively, simple custom
48 clients can be written in scripting languages such as Perl, Python or
49 Tcl, or more advanced clients such as GUI monitors can be written in C
50 with little difficulty.
52 Administration commands use a textual protocol. Each client command or
53 server response consists of a line of ASCII text terminated by a single
54 linefeed character. No command may be longer than 255 characters.
55 .SS "General structure"
56 Each command or response line consists of a sequence of
57 whitespace-separated tokens. The number and nature of whitespace
58 characters separating two tokens in a client command is not significant;
59 the server always uses a single space character. The first token in a
62 identifying the type of command or response contained. Keywords in
63 client commands are not case-sensitive; the server always uses uppercase
66 In order to allow tokens to contain internal whitespace, a quoting
67 mechanism is provided. Whitespace within matched pairs of quotes \(en
72 \(en is considered to be internal. Any character (other than newline)
73 may be escaped by preceding it with a backslash
75 in particular, this can be used to include quote characters. It is
76 impossible for a token to contain a newline character.
78 On output, the server will use double quotes when necessary.
80 For simple client command, the server responds with zero or more
82 lines, followed by either an
88 provides information requested in the command. An
90 response contains no further data. A
92 code is followed by a machine-readable explanation of why the command
95 Simple command processing is strictly synchronous: the server reads a
96 command, processes it, and responds, before reading the next command.
97 All commands can be run as simple commands. Long-running commands
102 block the client until they finish, but the rest of the server continues
104 .B "Background commands"
105 to find out how to issue long-running commands without blocking.
106 .SS "Asynchronous broadcasts"
107 There are three types of asynchronous broadcast messages which aren't
108 associated with any particular command. Clients can select which
109 broadcast messages they're interested in using the
115 message contains a machine-readable message warning of an error
116 encountered while processing a command, unexpected or unusual behaviour
117 by a peer, or a possible attack by an adversary. Under normal
118 conditions, the server shouldn't emit any warnings.
122 message contains a human-readable tracing message containing diagnostic
123 information. Trace messages are controlled using the
125 command-line option to the server, or the
127 administration command (see below). Support for tracing can be disabled
128 when the package is being configured, and may not be available in your
133 message is a machine-readable notification about some routine but
134 interesting event such as creation or destruction of peers.
135 .SS "Background commands"
140 take a long time to complete. To prevent these long-running commands
141 from tying up a server connection, they can be run in the background.
142 Not all commands can be run like this: the ones that can provide a
144 option, which must be supplied with a
147 A command may fail before it starts running in the background. In this
148 case, the server emits a
150 response, as usual. To indicate that a command has started running in
151 the background, the server emits a response of the form
152 .BI "BGDETACH " tag \fR,
155 is the value passed to the
157 option. From this point on, the server is ready to process more
158 commands and reply to them.
160 Responses to background commands are indicated by a line beginning with
166 followed by the command tag. These correspond to the
171 responses for simple commands:
173 indicates information from a background command which has not completed
178 indicates that a background command succeeded or failed, respectively.
180 A background command will never issue an
184 response: it will always detach and then issue any
189 .SS "Client-provided services"
190 .\"* 25 Service-related messages
191 An administration client can provide services to other clients.
192 Services are given names and versions. A client can attempt to
194 a particular service by issuing the
196 command. This may fail, for example, if some other client already
197 provides the same or later version of the service.
199 Other clients can issue
200 .I "service commands"
203 command; the service provider is expected to handle these commands and
206 There are three important asynchronous messages which will be sent to
209 .BI "SVCCANCEL " jobid
210 The named job has been cancelled, either because the issuing client has
211 disconnected or explicitly cancelled the job using the
215 .BI "SVCCLAIM " service " " version
216 Another client has claimed a later version of the named
218 The recipient is no longer the provider of this service.
220 .BI "SVCJOB " jobid " " service " " command " " args \fR...
221 Announces the arrival of a new job. The
223 is a simple token consisting of alphanumeric characters which
225 uses to identify this job.
227 The service provider can reply to the job using the commands
232 The first of these sends an
234 response and leaves the job active; the other two send an
238 response respectively, and mark the job as being complete.
242 is a potentially long-running command, it can be run in the background.
243 This detail is hidden from service providers:
245 will issue the corresponding
247 responses when appropriate.)
248 .SS "Network addresses"
249 A network address is a sequence of tokens. The first is a token
250 identifying the network address family. The length of an address and
251 the meanings of the subsequent tokens depend on the address family.
252 Address family tokens are not case-sensitive on input; on output, they
253 are always in upper-case.
255 At present, only one address family is understood.
257 .BI "INET " address " \fR[" port \fR]
258 An Internet socket, naming an IPv4 address and UDP port. On output, the
259 address is always in numeric dotted-quad form, and the port is given as
260 a plain number. On input, DNS hostnames and symbolic port names are
261 permitted; if omitted, the default port 4070 is used. Name resolution
262 does not block the main server, but will block the requesting client,
263 unless the command is run in the background.
265 If, on input, no recognized address family token is found, the following
266 tokens are assumed to represent an
268 address. Addresses output by the server always have an address family
270 .SS "Key-value output"
275 produce output in the form of
277 pairs, one per token. Neither the
283 Commands which enable or disable kinds of output (e.g.,
287 work in similar ways. They take a single optional argument, which
288 consists of a string of letters selecting message types, optionally
293 to disable, the subsequently listed types.
295 If the argument is omitted, the available message types are displayed,
298 line, in a fixed-column format. Column zero contains the key letter for
299 selecting that message type; column one contains either a space or a
301 sign, if the message type is disabled or enabled respectively; and a
302 textual description of the message type begins at column 3 and continues
303 to the end of the line.
305 Lowercase key letters control individual message types. Uppercase key
306 letters control collections of message types.
308 .\"--------------------------------------------------------------------------
309 .SH "COMMAND REFERENCE"
312 The commands provided are:
314 .BI "ADD \fR[" options "\fR] " peer " " address "\fR..."
315 Adds a new peer. The peer is given the name
317 the peer's public key is assumed to be in the file
319 (or whatever alternative file was specified in the
321 option on the command line). The
323 is the network address (see above for the format) at which the peer can
324 be contacted. The following options are recognized.
328 .BI "\-background " tag
329 Run the command in the background, using the given
333 Don't send an immediate challenge to the peer; instead, wait until it
334 sends us something before responding.
336 .BI "\-keepalive " time
337 Send a no-op packet if we've not sent a packet to the peer in the last
339 interval. This is useful for persuading port-translating firewalls to
340 believe that the `connection' is still active. The
342 is expressed as a nonnegative integer followed optionally by
348 for days, hours, minutes, or seconds respectively; if no suffix is
349 given, seconds are assumed.
354 to authenticate the peer. The default is to use the key tagged
358 The peer is a mobile device, and is likely to change address rapidly.
359 If a packet arrives from an unknown address, the server's usual response
360 is to log a warning and discard it. If the server knows of any mobile
361 peers, however, it will attempt to decrypt the packet using their keys,
362 and if one succeeds, the server will update its idea of the peer's
370 to authenticate to the peer. The default is to use the key named in the
372 command-line option, or a key with type
380 .BI "\-tunnel " tunnel
381 Use the named tunnel driver, rather than the default.
388 line reporting the IP address and port number stored for
391 .BI "ALGS \fR[" peer \fR]
392 Emits information about the cryptographic algorithms in use, in
395 is given, then describe the algorithms used in the association with that
396 peer; otherwise describe the default algorithms.
399 The keys are as follows.
402 Type of key-exchange group in use, currently either
407 .B kx-group-order-bits
408 Length of the group order, in bits. This gives an approximate measure
409 of the group strength.
412 Length of a group element, in bits. This may be useful when analyzing
416 The hash function in use, e.g.,
420 The mask-generating function in use, e.g.,
424 The size of the hash function's output, in octets.
427 The name of the bulk-crypto transform.
430 The amount of overhead, in bytes, caused by the crypto transform.
433 The name of the bulk data cipher in use, e.g.,
437 The length of key used by the bulk data cipher, in octets.
440 The block size of the bulk data cipher, or zero if it's not based on a
444 The maximum amount of data to be encrypted using a single key. (A new
445 key exchange is instigated well before the limit is reached, in order to
446 allow for a seamless changeover of keys.)
449 The message authentication algorithm in use, e.g.,
453 The length of the key used by the message authentication algorithm, in
457 The length of the message authentication tag, in octets.
459 The various sizes are useful, for example, when computing the MTU for a
462 is the MTU of the path to the peer, then the tunnel MTU should be
468 allowing 20 bytes of IP header, 8 bytes of UDP header, a packet type
469 octet, and the bulk-crypto transform overhead (which includes the
474 Cancels the background job with the named
477 .BI "CHECKCHAL " challenge
478 Verifies a challenge as being one earlier issued by
480 and not previously either passed to
482 or in a greeting message.
485 Causes the server to disassociate itself from its terminal and become a
486 background task. This only works once. A warning is issued.
488 .BI "EPING \fR[" options "\fR] " peer
489 Sends an encrypted ping to the peer, and expects an encrypted response.
490 This checks that the peer is running (and not being impersonated), and
491 that it can encrypt and decrypt packets correctly. Options and
492 responses are the same as for the
497 Requests the server to begin a new key exchange with
502 Requests a challenge. The challenge is returned in an
504 line, as a base64-encoded string. See
507 .BI "GREET " peer " " challenge
508 Sends a greeting packet containing the
510 (base-64 encoded) to the named
512 The expectation is that this will cause the peer to recognize us and
513 begin a key-exchange.
516 Causes the server to emit an
518 line for each command it supports. Each line lists the command name,
519 followed by the names of the arguments. This may be helpful as a memory
520 aid for interactive use, or for program clients probing for features.
525 line containing the name of the network interface used to collect IP
526 packets which are to be encrypted and sent to
528 Used by configuration scripts so that they can set up routing tables
529 appropriately after adding new peers.
534 line giving the tag for each outstanding background job.
537 Causes the server to forget all about
539 All keys are destroyed, and no more packets are sent. No notification
540 is sent to the peer: if it's important that the peer be notified, you
541 must think of a way to do that yourself.
544 For each currently-known peer, an
546 line is written containing the peer's name, as given to
549 .BI "NOTIFY " tokens\fR...
552 notification to all interested administration clients.
555 Returns information about a peer, in key-value form. The following keys
560 The tunnel driver used for this peer.
563 The keepalive interval, in seconds, or zero if no keepalives are to be
567 The (short) key tag being used for the peer, as passed to the
572 The full key tag of the peer's public key currently being used. This
573 may change during the life of the association.
576 The private key tag being used for the peer, as passed to the
580 command-line option. If neither of these was given explicitly, the
581 private key tag is shown as
583 since there is no fixed tag used under these circumstances.
585 .B current-private-key
586 The full key tag of the private key currently being used for this
587 association. This may change during the life of the association.
590 .BI "PING \fR[" options "\fR] " peer
591 Send a transport-level ping to the peer. The ping and its response are
592 not encrypted or authenticated. This command, possibly in conjunction
593 with tracing, is useful for ensuring that UDP packets are actually
594 flowing in both directions. See also the
600 line is printed describing the outcome:
603 .BI "ping-ok " millis
604 A response was received
606 after the ping was sent.
609 No response was received within the time allowed.
612 The peer was killed (probably by another admin connection) before a
613 response was received.
616 Options recognized for this command are:
620 .BI "\-background " tag
621 Run the command in the background, using the given
624 .BI "\-timeout " time
627 seconds before giving up on a response. The default is 5 seconds. The
629 is expressed as a nonnegative integer followed optionally by
635 for days, hours, minutes, or seconds respectively; if no suffix is
636 given, seconds are assumed.
643 line containing just the number of the UDP port used by the
645 server. If you've allowed your server to allocate a port dynamically,
646 this is how to find out which one it chose.
649 Instructs the server to recheck its keyring files. The server checks
650 these periodically anyway but it may be necessary to force a recheck,
651 for example after adding a new peer key.
654 Instructs the server to exit immediately. A warning is sent.
657 Returns information about the server, in the form of key-value pairs.
658 The following keys are used.
662 A keyword naming the implementation of the
664 server. The current implementation is called
668 The server's version number, as reported by
676 if the server has or hasn't (respectively) become a daemon.
679 .BI "SETIFNAME " peer " " new-name
680 Informs the server that the
682 tunnel-interface name has been changed to
684 This is useful if firewalling decisions are made based on interface
685 names: a setup script for a particular peer can change the name, and
686 then update the server's records so that they're accurate.
688 .BI "SVCCLAIM " service " " version
689 Attempts to claim the named
693 The claim is successful if the service is currently unclaimed, or if
694 a version earlier than
696 is provided; otherwise the command fails with the error
697 .BR "service-exists" .
699 .BI "SVCENSURE " service " \fR[" version \fR]
702 is provided, and (if specified) to at least the given
704 An error is reported if these conditions are not met; otherwise the
705 command succeeds silently.
707 .BI "SVCFAIL " jobid " " tokens \fR...
712 response to the service job with the given
716 as the reason for failure. The job is closed.
718 .BI "SVCINFO " jobid " " tokens \fR...
723 response to the service job with the given
727 as the info message. The job remains open.
730 Output a line of the form
737 for each service currently provided.
745 response to the service job with the given
749 .BI "SVCQUERY " service
752 lines in key-value format, describing the named
754 The following keys are used.
761 The service's version string.
764 .BI "SVCRELEASE " service
765 Announce that the client no longer wishes to provide the named
768 .BI "SVCSUBMIT \fR[" options "\fR] " service " " command " " arguments \fR...
769 Submit a job to the provider of the given
775 The following options are accepted.
779 .BI "\-background " tag
780 Run the command in the background, using the given
783 .BI "\-version " version
784 Ensure that at least the given
786 of the service is available before submitting the job.
793 lines, each containing one or more statistics in the form
794 .IB name = value \fR.
795 The statistics-gathering is experimental and subject to change.
797 .BR "TRACE " [\fIoptions\fP]
798 Selects trace outputs: see
800 above. Message types provided are:
803 Currently, the following tracing options are supported:
806 Tunnel events: reception of packets to be encrypted, and injection of
807 successfully-decrypted packets.
810 Peer management events: creation and destruction of peer attachments,
811 and arrival of messages.
814 Administration interface: acceptance of new connections, and handling of
815 the backgroud name-resolution required by the
820 Handling of symmetric keysets: creation and expiry of keysets, and
821 encryption and decryption of messages.
824 Key exchange: reception, parsing and emission of key exchange messages.
827 Key management: loading keys and checking for file modifications.
830 Display information about challenge issuing and verification.
833 Display contents of packets sent and received by the tunnel and/or peer
837 Display inputs, outputs and intermediate results of cryptographic
838 operations. This includes plaintext and key material. Use with
850 outputs provide extra detail for other outputs. Specifying
856 isn't useful; neither is specifying
867 For each available tunnel driver, an
869 line is printed giving its name.
872 Causes the server to emit an
874 line stating its software version, as two tokens: the server name, and
875 its version string. The server name
877 is reserved to the Straylight/Edgeware implementation.
879 .BR "WATCH " [\fIoptions\fP]
880 Enables or disables asynchronous broadcasts
881 .IR "for the current connection only" .
884 above. The default watch state for the connection the server opens
885 automatically on stdin/stdout is to show warnings and trace messages;
886 other connections show no asynchronous broadcast messages. (This is
887 done in order to guarantee that a program reading the server's stdout
888 does not miss any warnings.)
891 Message types provided are:
909 .BI "WARN " tokens\fR...
912 warning to all interested administration clients.
914 .\"--------------------------------------------------------------------------
917 .\"* 20 Error messages (FAIL codes)
922 messages are sent to clients as a result of errors during command
930 server is already running as a daemon.
932 .BI "bad-addr-syntax " message
933 (For commands accepting socket addresses.) The address couldn't be
936 .BI "bad-syntax " cmd " " message
937 (For any command.) The command couldn't be understood: e.g., the number
938 of arguments was wrong.
940 .BI "bad-time-spec " token
943 is not a valid time interval specification. Acceptable time
944 specifications are nonnegative integers followed optionally by
950 for days, hours, minutes, or seconds, respectively.
952 .BI "bad-trace-option " char
955 An unknown trace option was requested.
957 .BI "bad-watch-option " char
960 An unknown watch option was requested.
962 .BI "daemon-error " ecode " " message
965 An error occurred during the attempt to become a daemon, as reported by
968 .BI "invalid-port " number
971 The given port number is out of range.
973 .BI "not-service-provider " service
976 The invoking client is not the current provider of the named
978 and is therefore not allowed to release it.
980 .BI "peer-create-fail " peer
985 failed for some reason. A warning should have been emitted explaining
988 .BI "peer-addr-exists " address\fR...
991 There is already a peer with the given
994 .BI "peer-exists " peer
997 There is already a peer named
1000 .B "ping-send-failed"
1001 The attempt to send a ping packet failed, probably due to lack of
1004 .BI "resolve-error " hostname
1009 could not be resolved.
1011 .BI "resolver-timeout " hostname
1016 took too long to resolve.
1018 .BI "service-exists " service " " version
1021 Another client is already providing the stated
1026 .BI "service-too-old " service " " version
1035 is available, which does not meet the stated requirements.
1037 .BI "tag-exists " tag
1038 (For long-running commands.) The named
1040 is already the tag of an outstanding job.
1042 .BI "unknown-command " token
1047 .BI "unknown-jobid " jobid
1055 is not recognized as identifying an outstanding job. It may have just
1058 .BI "unknown-peer " name
1066 There is no peer called
1069 .BI "unknown-port " port
1074 couldn't be found in
1077 .BI "unknown-service " service
1086 is not recognized as the name of a client-provided service.
1088 .BI "unknown-tag " tag
1093 is not the tag for any outstanding background job. It may have just
1096 .\"--------------------------------------------------------------------------
1099 .\"* 30 Notification broadcasts (NOTE codes)
1100 The following notifications are sent to clients who request them.
1102 .BI "ADD " peer " " ifname " " address \fR...
1103 A new peer has been added. The peer's name is
1105 its tunnel is network interface
1107 and its network address is
1111 The server has forked off into the sunset and become a daemon.
1113 .BI "GREET " challenge " " address \fR...
1114 A valid greeting was received, with the given challenge (exactly as it
1127 finished successfully.
1132 has begun or restarted. If key exchange keeps failing, this message
1133 will be repeated periodically.
1135 .BI "NEWADDR " peer " " address
1138 IP address has been changed to
1141 .BI "NEWIFNAME " peer " " old-name " " new-name
1144 tunnel interface name has been changed from
1152 .BI "SVCCLAIM " service " " version
1155 is now available, at the stated
1158 .BI "SVCRELEASE " service
1161 is no longer available.
1163 .BI "USER " tokens\fR...
1164 An administration client issued a notification using the
1168 .\"--------------------------------------------------------------------------
1171 .\"* 40 Warning broadcasts (WARN codes)
1173 There are many possible warnings. They are categorized according to
1176 Many of these warnings report system errors. These are reported as a
1177 pair of tokens, described below as
1183 is a string of the form
1187 value of the error; the
1189 is the `human-readable' form of the message, as reported by
1191 .SS "ABORT warnings"
1192 These all indicate that the
1194 server has become unable to continue. If enabled, the server will dump
1195 core in its configuration directory.
1197 .BI "ABORT repeated-select-errors"
1198 The main event loop is repeatedly failing. If the server doesn't quit,
1199 it will probably waste all available CPU doing nothing.
1200 .SS "ADMIN warnings"
1201 These indicate a problem with the administration socket interface.
1203 .BI "ADMIN accept-error " ecode " " message
1204 There was an error while attempting to accept a connection from a new
1207 .BI "ADMIN client-write-error " ecode " " message
1208 There was an error sending data to a client. The connection to the
1209 client has been closed.
1211 These indicate errors in challenges, either in the
1213 command or in greeting packets.
1215 .B "CHAL impossible-challenge"
1216 The server hasn't issued any challenges yet. Quite how anyone else
1217 thought he could make one up is hard to imagine.
1219 .B "CHAL incorrect-tag"
1220 Challenge received contained the wrong authentication data. It might be
1221 very stale, or a forgery.
1223 .B "CHAL invalid-challenge"
1224 Challenge received was the wrong length. We might have changed MAC
1225 algorithms since the challenge was issued, or it might just be rubbish.
1227 .B "CHAL replay duplicated-sequence"
1228 Challenge received was a definite replay of an old challenge. Someone's
1231 .B "CHAL replay old-sequence"
1232 Challenge received was old, but maybe not actually a replay. Try again.
1233 .SS "KEYMGMT warnings"
1234 These indicate a problem with the keyring files, or the keys stored in
1235 them. The first token is either
1241 in the descriptions below) indicating which keyring file is problematic,
1242 and the second token is the filename of the keyring. Frequently a key
1243 tag may be given next, preceded by the token
1246 .BI "KEYMGMT public-keyring " file " key " tag " algorithm-mismatch"
1247 A peer's public key doesn't request the same algorithms as our private
1250 .BI "KEYMGMT " which "-keyring " file " key " tag " bad-tag-length " len
1251 The key attributes specify the length of MAC tag as
1253 but this is an invalid value \(en either too large or not a multiple of
1256 .BI "KEYMGMT " which "-keyring " file " key " tag " bad-tag-length-string " str
1257 The key attributes contain
1259 where a MAC tag length was expected. The key was generated wrongly.
1261 .BI "KEYMGMT private-keyring " file " key " tag " changed-group"
1262 The private keyring has been changed, but the new private key can't be
1263 used because it uses a different group for Diffie\(enHellman key
1266 .BI "KEYMGMT " which "-keyring " file " io-error " ecode " " message
1267 A system error occurred while opening or reading the keyring file.
1269 .BI "KEYMGMT " which "-keyring " file " key " tag " unknown-bulk-transform " bulk
1270 The key specifies the use of an unknown bulk-crypto transform
1272 Maybe the key was generated wrongly, or maybe the version of Catacomb
1273 installed is too old.
1275 .BI "KEYMGMT " which "-keyring " file " key " tag " unknown-cipher " cipher
1276 The key specifies the use of an unknown symmetric encryption algorithm
1278 Maybe the key was generated wrongly, or maybe the version of
1279 Catacomb installed is too old.
1281 .BI "KEYMGMT " which "-keyring " file " key " tag " unknown-group-type " type
1282 The key specifies the use of a Diffie\(enHellman group of an unknown
1284 Maybe the key was generated wrongly, or maybe the version of
1288 .BI "KEYMGMT " which "-keyring " file " key " tag " unknown-hash " hash
1289 The key specifies the use of an unknown hash function
1291 Maybe the key was generated wrongly, or maybe the version of Catacomb
1292 installed is too old.
1294 .BI "KEYMGMT " which "-keyring " file " key " tag " unknown-mac " mac
1295 The key specifies the use of an unknown message authentication code
1297 Maybe the key was generated wrongly, or maybe the version of Catacomb
1298 installed is too old.
1300 .BI "KEYMGMT " which "-keyring " file " key " tag " unknown-mgf-cipher " mgf
1301 The key specifies the use of an unknown symmetric encryption function
1303 for mask generation. Maybe the key was generated wrongly, or maybe the
1304 version of Catacomb installed is too old.
1306 .BI "KEYMGMT " which "-keyring " file " key " tag " no-hmac-for-hash " hash
1307 No message authentication code was given explicitly, and there's no
1308 implementation of HMAC for the selected hash function
1311 .BI "KEYMGMT " which "-keyring " file " key " tag " " alg " " name " no-key-size " hashsz
1318 The named algorithm requires more key material than the hash function
1319 can provide. You must change either the hash function, or the cipher or
1322 .BI "KEYMGMT " which "-keyring " file " key " tag " mgf " mgf " restrictive-key-schedule"
1323 The cipher selected for mask-generation is unsuitable because it can't
1324 accept arbitrary-sized keys.
1326 .BI "KEYMGMT " which "-keyring " file " key-not-found " tag
1329 couldn't be found in the keyring.
1331 .BI "KEYMGMT " which "-keyring " file " line " line " " message
1332 The contents of the keyring file are invalid. There may well be a bug
1337 These indicate problems during key-exchange. Many indicate either a bug
1338 in the server (either yours or the remote one), or some kind of attack
1339 in progress. All name a
1341 as the second token: this is the peer the packet is apparently from,
1342 though it may have been sent by an attacker instead.
1344 In the descriptions below,
1346 is one of the tokens
1355 .BI "KX " peer " algorithms-mismatch local-private-key " privtag " peer-public-key " pubtag
1356 The algorithms specified in the peer's public key
1358 don't match the ones described in the private key
1361 .BI "KX " peer " bad-expected-reply-log"
1364 uses in its protocol contain a check value which proves that the
1365 challenge is honest. This message indicates that the check value
1366 supplied is wrong: someone is attempting to use bogus challenges to
1369 server to leak private key information. No chance!
1371 .BI "KX " peer " decrypt-failed reply\fR|\fBswitch-ok"
1372 A symmetrically-encrypted portion of a key-exchange message failed to
1375 .BI "KX " peer " invalid " msgtoken
1376 A key-exchange message was malformed. This almost certainly indicates a
1379 .BI "KX " peer " incorrect cookie\fR|\fBswitch-rq\fR|\fBswitch-ok"
1380 A message didn't contain the right magic data. This may be a replay of
1381 some old exchange, or random packets being sent in an attempt to waste
1384 .BI "KX " peer " " which "-key-expired"
1385 The local private key or the peer's public key (distinguished by
1387 has expired. Either you or the peer's maintainer should have arranged
1388 for a replacement before now.
1390 .BI "KX " peer " sending-cookie"
1391 We've received too many bogus pre-challenge messages. Someone is trying
1392 to flood us with key-exchange messages and make us waste CPU on doing
1393 hard asymmetric crypto sums.
1395 .BI "KX " peer " unexpected " msgtoken
1396 The message received wasn't appropriate for this stage of the key
1397 exchange process. This may mean that one of our previous packets got
1400 it may simply mean that the peer has recently restarted.
1402 .BI "KX " peer " unknown-challenge"
1403 The peer is asking for an answer to a challenge which we don't know
1404 about. This may mean that we've been inundated with challenges from
1405 some malicious source
1406 .I who can read our messages
1407 and discarded the valid one.
1409 .BI "KX " peer " unknown-message 0x" nn
1410 An unknown key-exchange message arrived.
1412 These are largely concerned with management of peers and the low-level
1413 details of the network protocol. The second token is usually the name of
1416 if none is relevant.
1418 .BI "PEER " peer " bad-packet no-type"
1419 An empty packet arrived. This is very strange.
1421 .BI "PEER " peer " bad-packet unknown-category 0x" nn
1422 The message category
1424 (in hex) isn't understood. Probably a strange random packet from
1425 somewhere; could be an unlikely bug.
1427 .BI "PEER " peer " bad-packet unknown-type 0x" nn
1430 (in hex) isn't understood. Probably a strange random packet from
1431 somewhere; could be an unlikely bug.
1433 .BI "PEER " peer " corrupt-encrypted-ping"
1434 The peer sent a ping response which matches an outstanding ping, but its
1435 payload is wrong. There's definitely a bug somewhere.
1437 .BI "PEER " peer " corrupt-transport-ping"
1438 The peer (apparently) sent a ping response which matches an outstanding
1439 ping, but its payload is wrong. Either there's a bug, or the bad guys
1440 are playing tricks on you.
1442 .BI "PEER " peer " decrypt-failed"
1443 An encrypted IP packet failed to decrypt. It may have been mangled in
1444 transit, or may be a very old packet from an expired previous session
1445 key. There is usually a considerable overlap in the validity periods of
1446 successive session keys, so this shouldn't occur unless the key exchange
1447 takes ages or fails.
1449 .BI "PEER " peer " malformed-encrypted-ping"
1450 The peer sent a ping response which is hopelessly invalid. There's
1451 definitely a bug somewhere.
1453 .BI "PEER " peer " malformed-transport-ping"
1454 The peer (apparently) sent a ping response which is hopelessly invalid.
1455 Either there's a bug, or the bad guys are playing tricks on you.
1457 .BI "PEER " peer " packet-build-failed"
1458 There wasn't enough space in our buffer to put the packet we wanted to
1459 send. Shouldn't happen.
1461 .BI "PEER \- socket-read-error " ecode " " message
1462 An error occurred trying to read an incoming packet.
1464 .BI "PEER " peer " socket-write-error " ecode " " message
1465 An error occurred attempting to send a network packet. We lost that
1468 .BI "PEER " peer " unexpected-encrypted-ping 0x" id
1469 The peer sent an encrypted ping response whose id doesn't match any
1470 outstanding ping. Maybe it was delayed for longer than the server was
1471 willing to wait, or maybe the peer has gone mad.
1473 .BI "PEER \- unexpected-source " address\fR...
1474 A packet arrived from
1476 (a network address \(en see above), but no peer is known at that
1477 address. This may indicate a misconfiguration, or simply be a result of
1478 one end of a connection being set up before the other.
1480 .BI "PEER " peer " unexpected-transport-ping 0x" id
1481 The peer (apparently) sent a transport ping response whose id doesn't
1482 match any outstanding ping. Maybe it was delayed for longer than the
1483 server was willing to wait, or maybe the peer has gone mad; or maybe
1484 there are bad people trying to confuse you.
1485 .SS "SERVER warnings"
1486 These indicate problems concerning the server process as a whole.
1488 .BI "SERVER ignore signal " name
1489 A signal arrived, but the server ignored it. Currently this happens for
1491 because that's a popular way of telling daemons to re-read their
1492 configuration files. Since
1494 re-reads its keyrings automatically and has no other configuration
1495 files, it's not relevant, but it seemed better to ignore the signal than
1498 .BI "SERVER quit signal " \fR[\fInn\fR|\fIname\fR]
1499 A signal arrived and
1503 .BI "SERVER quit admin-request"
1504 A client of the administration interface issued a
1508 .BI "SERVER quit foreground-eof"
1509 The server is running in foreground mode (the
1511 option), and encountered end-of-file on standard input.
1513 .BI "SERVER select-error " ecode " " message
1514 An error occurred in the server's main event loop. This is bad: if it
1515 happens too many times, the server will abort.
1517 These are concerned with the symmetric encryption and decryption
1520 .BI "SYMM replay old-sequence"
1521 A packet was received with an old sequence number. It may just have
1522 been delayed or duplicated, or it may have been an attempt at a replay
1525 .BI "SYMM replay duplicated-sequence"
1526 A packet was received with a sequence number we've definitely seen
1527 before. It may be an accidental duplication because the 'net is like
1528 that, or a deliberate attempt at a replay.
1530 These concern the workings of the system-specific tunnel driver. The
1531 second token is the name of the tunnel interface in question, or
1535 .BI "TUN \- bsd no-tunnel-devices"
1536 The driver couldn't find an available tunnel device. Maybe if you
1539 files, it will work.
1541 .BI "TUN \- " tun-name " open-error " device " " ecode " " message
1542 An attempt to open the tunnel device file
1546 .BI "TUN \- linux config-error " ecode " " message
1547 Configuring the Linux TUN/TAP interface failed.
1549 .BI "TUN " ifname " " tun-name " read-error " ecode " " message
1550 Reading from the tunnel device failed.
1552 .BI "TUN " ifname " " tun-name " write-error " ecode " " message
1553 Writing from the tunnel device failed.
1555 .BI "TUN " ifname " slip bad-escape"
1556 The SLIP driver encountered a escaped byte it wasn't expecting to see.
1557 The erroneous packet will be ignored.
1559 .BI "TUN " ifname " slip eof"
1560 The SLIP driver encountered end-of-file on its input descriptor.
1561 Pending data is discarded, and no attempt is made to read any more data
1562 from that interface ever.
1564 .BI "TUN " ifname " slip escape-end"
1565 The SLIP driver encountered an escaped `end' marker. This probably
1566 means that someone's been sending it junk. The erroneous packet is
1567 discarded, and we hope that we've rediscovered synchronization.
1569 .BI "TUN \- slip fork-error " ecode " " message
1570 The SLIP driver encountered an error forking a child process while
1571 allocating a new dynamic interface.
1573 .BI "TUN \- slip no-slip-interfaces"
1574 The driver ran out of static SLIP interfaces. Either preallocate more,
1575 or use dynamic SLIP interface allocation.
1577 .BI "TUN " ifname " slip overflow"
1578 The SLIP driver gave up reading a packet because it got too large.
1580 .BI "TUN \- slip pipe-error " ecode " " message
1581 The SLIP driver encountered an error creating pipes while allocating a
1582 new dynamic interface.
1584 .BI "TUN \- slip read-ifname-failed " ecode " " message
1585 The SLIP driver encountered an error reading the name of a dynamically
1586 allocated interface. Maybe the allocation script is broken.
1588 .BI "TUN \- unet config-error " ecode " " message
1589 Configuring the Linux Unet interface failed. Unet is obsolete and
1590 shouldn't be used any more.
1592 .BI "TUN \- unet getinfo-error " ecode " " message
1593 Reading information about the Unet interface failed. Unet is obsolete
1594 and shouldn't be used any more.
1596 These are issued by administration clients using the
1600 .BI "USER " tokens\fR...
1601 An administration client issued a warning.
1604 .\"--------------------------------------------------------------------------
1607 .SS "Command responses"
1610 .BI "BGFAIL " tag " " tokens \fR...
1611 .BI "BGINFO " tag " " tokens \fR...
1613 .BI "FAIL " tokens \fR...
1614 .BI "INFO " tokens \fR...
1619 .\"--------------------------------------------------------------------------
1625 .IR "The Trivial IP Encryption Protocol" .
1627 .\"--------------------------------------------------------------------------
1630 Mark Wooding, <mdw@distorted.org.uk>
1632 .\"----- That's all, folks --------------------------------------------------