2 .TH tripe-admin 5 "18 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
4 tripe-admin \- administrator commands for TrIPE
6 This manual page describes the administration interface provided by the
12 program can be used either interactively or in scripts to communicate
13 with the server using this interface. Alternatively, simple custom
14 clients can be written in scripting languages such as Perl, Python or
15 Tcl, or more advanced clients such as GUI monitors can be written in C
16 with little difficulty.
18 By default, the server listens for admin connections on the Unix-domain
20 .BR /var/lib/tripe/tripesock .
21 Administration commands use a simple textual protocol. Each client
22 command or server response consists of a line of ASCII text terminated
23 by a single linefeed character. No command may be longer than 255
25 .SS "General structure"
26 Each command or response line consists of a sequence of
27 whitespace-separated words. The number and nature of whitespace
28 characters separating two words in a client command is not significant;
29 the server always uses a single space character. The first word in a
32 identifying the type of command or response contained. Keywords in
33 client commands are not case-sensitive; the server always uses uppercase
35 .SS "Server responses"
36 For client command, the server responds with zero or more
38 lines, followed by either an
44 provides information requested in the command. An
46 response contains no further data. A
48 code is followed by a machine-readable explanation of why the command
51 In addition, there are three types of asynchronous messages which
52 aren't associated with any particular command. The
54 message contains a machine-readable message warning of an error
55 encountered while processing a command, unexpected or unusual behaviour
56 by a peer, or a possible attack by an adversary. Under normal
57 conditions, the server shouldn't emit any warnings. The
59 message contains a human-readable tracing message containing diagnostic
60 information. Trace messages are controlled using the
62 command-line option to the server, or the
64 administration command (see below). Support for tracing can be disabled
65 when the package is being configured, and may not be available in your
68 message is a machine-readable notification about some routine but
69 interesting event such as creation or destruction of peers.
71 The presence of asynchronous messages can be controlled using the
74 .SS "Network addresses"
75 A network address is a sequence of words. The first is a token
76 identifying the network address family. The length of an address and
77 the meanings of the subsequent words depend on the address family.
78 Address family tokens are not case-sensitive on input; on output, they
79 are always in upper-case.
81 At present, only one address family is understood.
83 .BI "INET " address " " port
84 An Internet socket, naming an IPv4 address and UDP port. On output, the
85 address is always in numeric dotted-quad form, and the port is given as
86 a plain number. On input, DNS hostnames and symbolic port names are
87 permitted. Name resolution does not block the main server, but will
88 block the requesting client. This hopefully makes life simpler for
89 stupid clients. Complex clients which don't wish to be held up can open
90 extra connections or do the resolution themselves.)
92 If, on input, no recognised address family token is found, the following
93 words are assumed to represent an
96 .SH "COMMAND REFERENCE"
97 The commands provided are:
99 .BI "ADD " peer " " address\fR...
100 Adds a new peer. The peer is given the name
102 the peer's public key is assumed to be in the file
104 (or whatever alternative file was specified in the
106 option on the command line). The
108 is the network address (see above for the format) at which the peer can
114 line reporting the IP address and port number stored for
118 Causes the server to disassociate itself from its terminal and become a
119 background task. This only works once. A warning is issued.
122 Causes the server to emit an
124 line for each command it supports. Each line lists the command name,
125 followed by the names of the arguments. This may be helpful as a memory
126 aid for interactive use, or for program clients probing for features.
131 line containing the name of the network interface used to collect IP
132 packets which are to be encrypted and sent to
134 Used by configuration scripts so that they can set up routing tables
135 appropriately after adding new peers.
138 Causes the server to forget all about
140 All keys are destroyed, and no more packets are sent. No notification
141 is sent to the peer: if it's important that the peer be notified, you
142 must think of a way to do that yourself.
145 For each currently-known peer, an
147 line is written containing the peer's name, as given to
150 .BI "NOTIFY " tokens\fR...
153 notification to all interested administration clients.
158 line containing just the number of the UDP port used by the
160 server. If you've allowed your server to allocate a port dynamically,
161 this is how to find out which one it chose.
164 Instructs the server to exit immediately. A warning is sent.
169 lines, each containing one or more statistics in the form
170 .IB name = value \fR.
171 The statistics-gathering is experimental and subject to change.
173 .BR "TRACE " [\fIoptions\fP]
174 A trace argument consists of a string of letters (listed below)
175 selecting trace outputs, optionally interspersed with
179 to disable, the subsequently listed outputs; the initial behaviour is to
180 enable listed outputs. For example, the string
182 enables tracing of peer management, admin-connection handling and
183 key-exchange processing, and disables tracing of symmetric keyset
184 management and the system-specific tunnel driver. If no argument is
185 given, a table is returned showing the available tracing option letters
186 and their meanings. Programs should not attempt to parse this table:
187 its format is not guaranteed to remain the same.
190 Currently, the following tracing options are supported:
193 Tunnel events: reception of packets to be encrypted, and injection of
194 successfully-decrypted packets.
197 Peer management events: creation and destruction of peer attachments,
198 and arrival of messages.
201 Administration interface: acceptance of new connections, and handling of
202 the backgroud name-resolution required by the
207 Display contents of packets sent and received by the tunnel and/or peer
211 Display inputs, outputs and intermediate results of cryptographic
212 operations. This includes plaintext and key material. Use with
216 Handling of symmetric keysets: creation and expiry of keysets, and
217 encryption and decryption of messages.
220 Key exchange: reception, parsing and emission of key exchange messages.
223 Key management: loading keys and checking for file modifications.
231 outputs provide extra detail for other outputs. Specifying
237 isn't useful; neither is specifying
249 .BR "WATCH " [\fIoptions\fP]
250 Enables or disables asynchronous messages
251 .IR "for the current connection only" .
252 This command has no effect on other connections. A watch argument
253 consists of a string of letters (listed below) selecting message types,
254 optionally interspersed with
258 to disable, the subsequently listed types, similar to
260 above. The default watch state for the connection the server opens
261 automatically on stdin/stdout is to show warnings and trace messages;
262 other connections show no asynchronous messages. (This is done in order
263 to guarantee that a program reading the server's stdout does not miss
267 Currently, the following watch options are supported:
286 Causes the server to emit an
288 line stating its software version, as two words: the server name, and
289 its version string. The server name
291 is reserved to the Straylight/Edgeware implementation.
293 .BI "WARN " tokens\fR...
296 warning to all interested administration clients.
300 messages are sent to clients as a result of errors during command
308 server is already running as a daemon.
310 .BI "bad-syntax \-\- " message
311 (For any command.) The command couldn't be understood: e.g., the number
312 of arguments was wrong.
314 .BI "bad-trace-option " char
317 An unknown trace option was requested.
319 .BI "bad-watch-option " char
322 An unknown watch option was requested.
324 .BI "daemon-error \-\- " message
327 An error occurred during the attempt to become a daemon, as reported by
330 .BI "invalid-port " number
333 The given port number is out of range.
335 .BI "peer-create-fail " peer
340 failed for some reason. A warning should have been emitted explaining
343 .BI "peer-exists " peer
346 There is already a peer named
349 .BI "resolve-error " hostname
354 could not be resolved.
356 .BI "resolver-timeout " hostname
361 took too long to resolve.
363 .BI "unknown-command " token
368 .BI "unknown-peer " name
375 There is no peer called
378 .BI "unknown-service " service
386 The following notifications are sent to clients who request them.
388 .BI "ADD " peer " " address \fR...
389 A new peer has been added. The peer's name is
391 and its network address is
395 The server has forked off into the sunset and become a daemon.
405 finished successfully.
410 has begun or restarted. If key exchange keeps failing, this message
411 will be repeated periodically.
413 .BI "USER " tokens\fR...
414 An administration client issued a notification using the
418 There are many possible warnings. They are categorized according to
421 These all indicate that the
423 server has become unable to continue. If enabled, the server will dump
424 core in its configuration directory.
426 .BI "ABORT repeated-select-errors"
427 The main event loop is repeatedly failing. If the server doesn't quit,
428 it will probably waste all available CPU doing nothing.
430 These indicate a problem with the administration socket interface.
432 .BI "ADMIN accept-error \-\- " message
433 There was an error while attempting to accept a connection from a new
436 .BI "ADMIN client-read-error \-\- " message
437 There was an error sending data to a client. The connection to the
438 client has been closed.
439 .SS "KEYMGMT warnings"
440 These indicate a problem with the keyring files, or the keys stored in
443 .BI "KEYMGMT bad-private-key \-\- " message
444 The private key could not be read, or failed a consistency check. If
445 there was a problem with the file, usually there will have been
447 warnings before this.
449 .BI "KEYMGMT bad-public-keyring \-\- " message
450 The public keyring couldn't be read. Usually, there will have been
452 warnings before this.
454 .BI "KEYMGMT key-file-error " file ":" line " \-\- " message
455 Reports a specific error with the named keyring file. This probably
459 .BI "KEYMGMT public-key " tag " " tokens\fR...
460 These messages all indicate a problem with the public key named
463 .BI "KEYMGMT public-key " tag " algorithm-mismatch"
464 The algorithms specified on the public key don't match the ones for our
465 private key. All the peers in a network have to use the same
468 .BI "KEYMGMT public-key " tag " bad \-\- " message
469 The public key couldn't be read, or is invalid.
471 .BI "KEYMGMT public-key " tag " bad-public-group-element"
472 The public key is invalid. This may indicate a malicious attempt to
473 introduce a bogus key.
475 .BI "KEYMGMT public-key " tag " bad-algorithm-selection"
476 The algorithms listed on the public key couldn't be understood. The
477 algorithm selection attributes are probably malformed and need fixing.
479 .BI "KEYMGMT public-key " tag " incorrect-group"
480 The public key doesn't use the same group as our private key. All the
481 peers in a network have to use the same group.
483 .BI "KEYMGMT public-key " tag " not-found"
484 The public key for peer
486 wasn't in the public keyring.
488 .BI "KEYMGMT public-key " tag " unknown-type"
489 The type of the public key isn't understood. Maybe you need to upgrade
492 (Even if you do, you'll have to regenerate your keys.)
494 These indicate problems during key-exchange. Many indicate either a bug
495 in the server (either yours or the remote one), or some kind of attack
496 in progress. All name a
498 as the second token: this is the peer the packet is apparently from,
499 though it may have been sent by an attacker instead.
501 In the descriptions below,
512 .BI "KX " peer " bad-expected-reply-log"
515 uses in its protocol contain a check value which proves that the
516 challenge is honest. This message indicates that the check value
517 supplied is wrong: someone is attempting to use bogus challenges to
520 server to leak private key information. No chance!
522 .BI "KX " peer " decrypt-failed reply\fR|\fBswitch-ok"
523 A symmetrically-encrypted portion of a key-exchange message failed to
526 .BI "KX " peer " invalid " msgtoken
527 A key-exchange message was malformed. This almost certainly indicates a
530 .BI "KX " peer " incorrect cookie\fR|\fBswitch-rq\fR|\fBswitch-ok"
531 A message didn't contain the right magic data. This may be a replay of
532 some old exchange, or random packets being sent in an attempt to waste
535 .BI "KX " peer " public-key-expired"
536 The peer's public key has expired. It's maintainer should have given
537 you a replacement before now.
539 .BI "KX " peer " sending-cookie"
540 We've received too many bogus pre-challenge messages. Someone is trying
541 to flood us with key-exchange messages and make us waste CPU on doing
542 hard asymmetric crypto sums.
544 .BI "KX " peer " unexpected " msgtoken
545 The message received wasn't appropriate for this stage of the key
546 exchange process. This may mean that one of our previous packets got
549 it may simply mean that the peer has recently restarted.
551 .BI "KX " peer " unknown-challenge"
552 The peer is asking for an answer to a challenge which we don't know
553 about. This may mean that we've been inundated with challenges from
554 some malicious source
555 .I who can read our messages
556 and discarded the valid one.
558 .BI "KX " peer " unknown-message 0x" nn
559 An unknown key-exchange message arrived.
561 These are largely concerned with management of peers and the low-level
562 details of the network protocol. The second word is usually the name of
567 .BI "PEER \- unexpected-source " address\fR...
568 A packet arrived from
570 (a network address \(en see above), but no peer is known at that
571 address. This may indicate a misconfiguration, or simply be a result of
572 one end of a connection being set up before the other.
574 .BI "PEER " peer " bad-packet no-type"
575 An empty packet arrived. This is very strange.
577 .BI "PEER " peer " bad-packet unknown-category 0x" nn
580 (in hex) isn't understood. Probably a strange random packet from
581 somewhere; could be an unlikely bug.
583 .BI "PEER " peer " bad-packet unknown-type 0x" nn
586 (in hex) isn't understood. Probably a strange random packet from
587 somewhere; could be an unlikely bug.
589 .BI "PEER " peer " decrypt-failed"
590 An encrypted IP packet failed to decrypt. It may have been mangled in
591 transit, or may be a very old packet from an expired previous session
592 key. There is usually a considerable overlap in the validity periods of
593 successive session keys, so this shouldn't occur unless the key exchange
596 .BI "PEER " peer " packet-build-failed"
597 There wasn't enough space in our buffer to put the packet we wanted to
598 send. Shouldn't happen.
600 .BI "PEER \- socket-read-error \-\- " message
601 An error occurred trying to read an incoming packet.
603 .BI "PEER " peer " socket-write-error \-\- " message
604 An error occurred attempting to send a network packet. We lost that
606 .SS "SERVER warnings"
607 These indicate problems concerning the server process as a whole.
609 .BI "SERVER ignore signal " name
610 A signal arrived, but the server ignored it. Currently this happens for
612 because that's a popular way of telling daemons to re-read their
613 configuration files. Since
615 re-reads its keyrings automatically and has no other configuration
616 files, it's not relevant, but it seemed better to ignore the signal than
619 .BI "SERVER quit signal " \fR[\fInn\fR|\fIname\fR]
624 .BI "SERVER quit admin-request"
625 A client of the administration interface issued a
629 .BI "SERVER select-error \-\- " message
630 An error occurred in the server's main event loop. This is bad: if it
631 happens too many times, the server will abort.
633 These are concerned with the symmetric encryption and decryption
636 .BI "SYMM replay old-sequence"
637 A packet was received with an old sequence number. It may just have
638 been delayed or duplicated, or it may have been an attempt at a replay
641 .BI "SYMM replay duplicated-sequence"
642 A packet was received with a sequence number we've definitely seen
643 before. It may be an accidental duplication because the 'net is like
644 that, or a deliberate attempt at a replay.
646 These concern the workings of the system-specific tunnel driver. The
647 second word is the name of the tunnel interface in question, or
651 .BI "TUN \- bsd no-tunnel-devices"
652 The driver couldn't find an available tunnel device. Maybe if you
657 .BI "TUN - open-error " device " \-\- " message
658 An attempt to open the tunnel device file
662 .BI "TUN " ifname " read-error \-\- " message
663 Reading from the tunnel device failed.
665 .BI "TUN \- linux config-error \-\- " message
666 Configuring the Linux TUN/TAP interface failed.
668 .BI "TUN \- unet config-error \-\- " message
669 Configuring the Linux Unet interface failed. Unet is obsolete and
670 shouldn't be used any more.
672 .BI "TUN \- unet getinfo-error \-\- " message
673 Reading information about the Unet interface failed. Unet is obsolete
674 and shouldn't be used any more.
676 .BI "TUN \- unet ifname-too-long \-\- " message
677 The Unet interface's name overflowed, so we couldn't read it properly.
678 Unet is obsolete and shouldn't be used any more.
680 These are issued by administration clients using the
684 .BI "USER " tokens\fR...
685 An administration client issued a warning.
690 .IR "The Trivial IP Encryption Protocol" .
692 Mark Wooding, <mdw@nsict.org>
~mdw / tripe / blob