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
153 line containing just the number of the UDP port used by the
155 server. If you've allowed your server to allocate a port dynamically,
156 this is how to find out which one it chose.
159 Instructs the server to exit immediately. A warning is sent.
164 lines, each containing one or more statistics in the form
165 .IB name = value \fR.
166 The statistics-gathering is experimental and subject to change.
168 .BR "TRACE " [\fIoptions\fP]
169 A trace argument consists of a string of letters (listed below)
170 selecting trace outputs, optionally interspersed with
174 to disable, the subsequently listed outputs; the initial behaviour is to
175 enable listed outputs. For example, the string
177 enables tracing of peer management, admin-connection handling and
178 key-exchange processing, and disables tracing of symmetric keyset
179 management and the system-specific tunnel driver. If no argument is
180 given, a table is returned showing the available tracing option letters
181 and their meanings. Programs should not attempt to parse this table:
182 its format is not guaranteed to remain the same.
185 Currently, the following tracing options are supported:
188 Tunnel events: reception of packets to be encrypted, and injection of
189 successfully-decrypted packets.
192 Peer management events: creation and destruction of peer attachments,
193 and arrival of messages.
196 Administration interface: acceptance of new connections, and handling of
197 the backgroud name-resolution required by the
202 Display contents of packets sent and received by the tunnel and/or peer
206 Display inputs, outputs and intermediate results of cryptographic
207 operations. This includes plaintext and key material. Use with
211 Handling of symmetric keysets: creation and expiry of keysets, and
212 encryption and decryption of messages.
215 Key exchange: reception, parsing and emission of key exchange messages.
218 Key management: loading keys and checking for file modifications.
226 outputs provide extra detail for other outputs. Specifying
232 isn't useful; neither is specifying
244 .BR "WATCH " [\fIoptions\fP]
245 Enables or disables asynchronous messages
246 .IR "for the current connection only" .
247 This command has no effect on other connections. A watch argument
248 consists of a string of letters (listed below) selecting message types,
249 optionally interspersed with
253 to disable, the subsequently listed types, similar to
255 above. The default watch state for the connection the server opens
256 automatically on stdin/stdout is to show warnings and trace messages;
257 other connections show no asynchronous messages. (This is done in order
258 to guarantee that a program reading the server's stdout does not miss
262 Currently, the following watch options are supported:
281 Causes the server to emit an
283 line stating its software version, as two words: the server name, and
284 its version string. The server name
286 is reserved to the Straylight/Edgeware implementation.
290 messages are sent to clients as a result of errors during command
298 server is already running as a daemon.
300 .BI "bad-syntax \-\- " message
301 (For any command.) The command couldn't be understood: e.g., the number
302 of arguments was wrong.
304 .BI "bad-trace-option " char
307 An unknown trace option was requested.
309 .BI "bad-watch-option " char
312 An unknown watch option was requested.
314 .BI "daemon-error \-\- " message
317 An error occurred during the attempt to become a daemon, as reported by
320 .BI "invalid-port " number
323 The given port number is out of range.
325 .BI "peer-create-fail " peer
330 failed for some reason. A warning should have been emitted explaining
333 .BI "peer-exists " peer
336 There is already a peer named
339 .BI "resolve-error " hostname
344 could not be resolved.
346 .BI "resolver-timeout " hostname
351 took too long to resolve.
353 .BI "unknown-command " token
358 .BI "unknown-peer " name
365 There is no peer called
368 .BI "unknown-service " service
376 The following notifications are sent to clients who request them.
378 .BI "ADD " peer " " address \fR...
379 A new peer has been added. The peer's name is
381 and its network address is
385 The server has forked off into the sunset and become a daemon.
395 finished successfully.
400 has begun or restarted. If key exchange keeps failing, this message
401 will be repeated periodically.
403 There are many possible warnings. They are categorized according to
406 These all indicate that the
408 server has become unable to continue. If enabled, the server will dump
409 core in its configuration directory.
411 .BI "ABORT repeated-select-errors"
412 The main event loop is repeatedly failing. If the server doesn't quit,
413 it will probably waste all available CPU doing nothing.
415 These indicate a problem with the administration socket interface.
417 .BI "ADMIN accept-error \-\- " message
418 There was an error while attempting to accept a connection from a new
421 .BI "ADMIN client-read-error \-\- " message
422 There was an error sending data to a client. The connection to the
423 client has been closed.
424 .SS "KEYMGMT warnings"
425 These indicate a problem with the keyring files, or the keys stored in
428 .BI "KEYMGMT bad-private-key \-\- " message
429 The private key could not be read, or failed a consistency check. If
430 there was a problem with the file, usually there will have been
432 warnings before this.
434 .BI "KEYMGMT bad-public-keyring \-\- " message
435 The public keyring couldn't be read. Usually, there will have been
437 warnings before this.
439 .BI "KEYMGMT key-file-error " file ":" line " \-\- " message
440 Reports a specific error with the named keyring file. This probably
444 .BI "KEYMGMT public-key " tag " " tokens\fR...
445 These messages all indicate a problem with the public key named
448 .BI "KEYMGMT public-key " tag " algorithm-mismatch"
449 The algorithms specified on the public key don't match the ones for our
450 private key. All the peers in a network have to use the same
453 .BI "KEYMGMT public-key " tag " bad \-\- " message
454 The public key couldn't be read, or is invalid.
456 .BI "KEYMGMT public-key " tag " bad-public-group-element"
457 The public key is invalid. This may indicate a malicious attempt to
458 introduce a bogus key.
460 .BI "KEYMGMT public-key " tag " bad-algorithm-selection"
461 The algorithms listed on the public key couldn't be understood. The
462 algorithm selection attributes are probably malformed and need fixing.
464 .BI "KEYMGMT public-key " tag " incorrect-group"
465 The public key doesn't use the same group as our private key. All the
466 peers in a network have to use the same group.
468 .BI "KEYMGMT public-key " tag " not-found"
469 The public key for peer
471 wasn't in the public keyring.
473 .BI "KEYMGMT public-key " tag " unknown-type"
474 The type of the public key isn't understood. Maybe you need to upgrade
477 (Even if you do, you'll have to regenerate your keys.)
479 These indicate problems during key-exchange. Many indicate either a bug
480 in the server (either yours or the remote one), or some kind of attack
481 in progress. All name a
483 as the second token: this is the peer the packet is apparently from,
484 though it may have been sent by an attacker instead.
486 In the descriptions below,
497 .BI "KX " peer " bad-expected-reply-log"
500 uses in its protocol contain a check value which proves that the
501 challenge is honest. This message indicates that the check value
502 supplied is wrong: someone is attempting to use bogus challenges to
505 server to leak private key information. No chance!
507 .BI "KX " peer " decrypt-failed \fR[\fBreply\fR|\fBswitch-ok\fR]"
508 A symmetrically-encrypted portion of a key-exchange message failed to
511 .BI "KX " peer " invalid " msgtoken
512 A key-exchange message was malformed. This almost certainly indicates a
515 .BI "KX " peer " incorrect \fR[\fBcookie\fR|\fBswitch-rq\fR|\fBswitch-ok\fR]"
516 A message didn't contain the right magic data. This may be a replay of
517 some old exchange, or random packets being sent in an attempt to waste
520 .BI "KX " peer " public-key-expired"
521 The peer's public key has expired. It's maintainer should have given
522 you a replacement before now.
524 .BI "KX " peer " sending-cookie"
525 We've received too many bogus pre-challenge messages. Someone is trying
526 to flood us with key-exchange messages and make us waste CPU on doing
527 hard asymmetric crypto sums.
529 .BI "KX " peer " unexpected " msgtoken
530 The message received wasn't appropriate for this stage of the key
531 exchange process. This may mean that one of our previous packets got
534 it may simply mean that the peer has recently restarted.
536 .BI "KX " peer " unknown-challenge"
537 The peer is asking for an answer to a challenge which we don't know
538 about. This may mean that we've been inundated with challenges from
539 some malicious source
540 .I who can read our messages
541 and discarded the valid one.
543 .BI "KX " peer " unknown-message 0x" nn
544 An unknown key-exchange message arrived.
546 These are largely concerned with management of peers and the low-level
547 details of the network protocol. The second word is usually the name of
552 .BI "PEER \- unexpected-source " address\fR...
553 A packet arrived from
555 (a network address \(en see above), but no peer is known at that
556 address. This may indicate a misconfiguration, or simply be a result of
557 one end of a connection being set up before the other.
559 .BI "PEER " peer " bad-packet no-type"
560 An empty packet arrived. This is very strange.
562 .BI "PEER " peer " bad-packet unknown-category 0x" nn
565 (in hex) isn't understood. Probably a strange random packet from
566 somewhere; could be an unlikely bug.
568 .BI "PEER " peer " bad-packet unknown-type 0x" nn
571 (in hex) isn't understood. Probably a strange random packet from
572 somewhere; could be an unlikely bug.
574 .BI "PEER " peer " decrypt-failed"
575 An encrypted IP packet failed to decrypt. It may have been mangled in
576 transit, or may be a very old packet from an expired previous session
577 key. There is usually a considerable overlap in the validity periods of
578 successive session keys, so this shouldn't occur unless the key exchange
581 .BI "PEER " peer " packet-build-failed"
582 There wasn't enough space in our buffer to put the packet we wanted to
583 send. Shouldn't happen.
585 .BI "PEER \- socket-read-error \-\- " message
586 An error occurred trying to read an incoming packet.
588 .BI "PEER " peer " socket-write-error \-\- " message
589 An error occurred attempting to send a network packet. We lost that
591 .SS "SERVER warnings"
592 These indicate problems concerning the server process as a whole.
594 .BI "SERVER ignore signal " name
595 A signal arrived, but the server ignored it. Currently this happens for
597 because that's a popular way of telling daemons to re-read their
598 configuration files. Since
600 re-reads its keyrings automatically and has no other configuration
601 files, it's not relevant, but it seemed better to ignore the signal than
604 .BI "SERVER quit signal " \fR[\fInn\fR|\fIname\fR]
609 .BI "SERVER quit admin-request"
610 A client of the administration interface issued a
614 .BI "SERVER select-error \-\- " message
615 An error occurred in the server's main event loop. This is bad: if it
616 happens too many times, the server will abort.
618 These are concerned with the symmetric encryption and decryption
621 .BI "SYMM replay old-sequence"
622 A packet was received with an old sequence number. It may just have
623 been delayed or duplicated, or it may have been an attempt at a replay
626 .BI "SYMM replay duplicated-sequence"
627 A packet was received with a sequence number we've definitely seen
628 before. It may be an accidental duplication because the 'net is like
629 that, or a deliberate attempt at a replay.
631 These concern the workings of the system-specific tunnel driver. The
632 second word is the name of the tunnel interface in question, or
636 .BI "TUN \- bsd no-tunnel-devices"
637 The driver couldn't find an available tunnel device. Maybe if you
642 .BI "TUN - open-error " device " \-\- " message
643 An attempt to open the tunnel device file
647 .BI "TUN " ifname " read-error \-\- " message
648 Reading from the tunnel device failed.
650 .BI "TUN \- linux config-error \-\- " message
651 Configuring the Linux TUN/TAP interface failed.
653 .BI "TUN \- unet config-error \-\- " message
654 Configuring the Linux Unet interface failed. Unet is obsolete and
655 shouldn't be used any more.
657 .BI "TUN \- unet getinfo-error \-\- " message
658 Reading information about the Unet interface failed. Unet is obsolete
659 and shouldn't be used any more.
661 .BI "TUN \- unet ifname-too-long \-\- " message
662 The Unet interface's name overflowed, so we couldn't read it properly.
663 Unet is obsolete and shouldn't be used any more.
668 .IR "The Trivial IP Encryption Protocol" .
670 Mark Wooding, <mdw@nsict.org>
~mdw / tripe / blob