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 " \fR[" options "\fR] " 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
109 be contacted. The following options are recognised.
112 .BI "-tunnel " tunnel
113 Use the named tunnel driver, rather than the default.
119 line reporting the IP address and port number stored for
123 Causes the server to disassociate itself from its terminal and become a
124 background task. This only works once. A warning is issued.
127 Causes the server to emit an
129 line for each command it supports. Each line lists the command name,
130 followed by the names of the arguments. This may be helpful as a memory
131 aid for interactive use, or for program clients probing for features.
136 line containing the name of the network interface used to collect IP
137 packets which are to be encrypted and sent to
139 Used by configuration scripts so that they can set up routing tables
140 appropriately after adding new peers.
143 Causes the server to forget all about
145 All keys are destroyed, and no more packets are sent. No notification
146 is sent to the peer: if it's important that the peer be notified, you
147 must think of a way to do that yourself.
150 For each currently-known peer, an
152 line is written containing the peer's name, as given to
155 .BI "NOTIFY " tokens\fR...
158 notification to all interested administration clients.
163 line containing just the number of the UDP port used by the
165 server. If you've allowed your server to allocate a port dynamically,
166 this is how to find out which one it chose.
169 Instructs the server to exit immediately. A warning is sent.
174 lines, each containing one or more statistics in the form
175 .IB name = value \fR.
176 The statistics-gathering is experimental and subject to change.
178 .BR "TRACE " [\fIoptions\fP]
179 A trace argument consists of a string of letters (listed below)
180 selecting trace outputs, optionally interspersed with
184 to disable, the subsequently listed outputs; the initial behaviour is to
185 enable listed outputs. For example, the string
187 enables tracing of peer management, admin-connection handling and
188 key-exchange processing, and disables tracing of symmetric keyset
189 management and the system-specific tunnel driver. If no argument is
190 given, a table is returned showing the available tracing option letters
191 and their meanings. Programs should not attempt to parse this table:
192 its format is not guaranteed to remain the same.
195 Currently, the following tracing options are supported:
198 Tunnel events: reception of packets to be encrypted, and injection of
199 successfully-decrypted packets.
202 Peer management events: creation and destruction of peer attachments,
203 and arrival of messages.
206 Administration interface: acceptance of new connections, and handling of
207 the backgroud name-resolution required by the
212 Display contents of packets sent and received by the tunnel and/or peer
216 Display inputs, outputs and intermediate results of cryptographic
217 operations. This includes plaintext and key material. Use with
221 Handling of symmetric keysets: creation and expiry of keysets, and
222 encryption and decryption of messages.
225 Key exchange: reception, parsing and emission of key exchange messages.
228 Key management: loading keys and checking for file modifications.
236 outputs provide extra detail for other outputs. Specifying
242 isn't useful; neither is specifying
254 .BR "WATCH " [\fIoptions\fP]
255 Enables or disables asynchronous messages
256 .IR "for the current connection only" .
257 This command has no effect on other connections. A watch argument
258 consists of a string of letters (listed below) selecting message types,
259 optionally interspersed with
263 to disable, the subsequently listed types, similar to
265 above. The default watch state for the connection the server opens
266 automatically on stdin/stdout is to show warnings and trace messages;
267 other connections show no asynchronous messages. (This is done in order
268 to guarantee that a program reading the server's stdout does not miss
272 Currently, the following watch options are supported:
291 Causes the server to emit an
293 line stating its software version, as two words: the server name, and
294 its version string. The server name
296 is reserved to the Straylight/Edgeware implementation.
298 .BI "WARN " tokens\fR...
301 warning to all interested administration clients.
305 messages are sent to clients as a result of errors during command
313 server is already running as a daemon.
315 .BI "bad-syntax \-\- " message
316 (For any command.) The command couldn't be understood: e.g., the number
317 of arguments was wrong.
319 .BI "bad-trace-option " char
322 An unknown trace option was requested.
324 .BI "bad-watch-option " char
327 An unknown watch option was requested.
329 .BI "daemon-error \-\- " message
332 An error occurred during the attempt to become a daemon, as reported by
335 .BI "invalid-port " number
338 The given port number is out of range.
340 .BI "peer-create-fail " peer
345 failed for some reason. A warning should have been emitted explaining
348 .BI "peer-exists " peer
351 There is already a peer named
354 .BI "resolve-error " hostname
359 could not be resolved.
361 .BI "resolver-timeout " hostname
366 took too long to resolve.
368 .BI "unknown-command " token
373 .BI "unknown-peer " name
380 There is no peer called
383 .BI "unknown-service " service
391 The following notifications are sent to clients who request them.
393 .BI "ADD " peer " " ifname " " address \fR...
394 A new peer has been added. The peer's name is
396 its tunnel is network interface
398 and its network address is
402 The server has forked off into the sunset and become a daemon.
412 finished successfully.
417 has begun or restarted. If key exchange keeps failing, this message
418 will be repeated periodically.
420 .BI "USER " tokens\fR...
421 An administration client issued a notification using the
425 There are many possible warnings. They are categorized according to
428 These all indicate that the
430 server has become unable to continue. If enabled, the server will dump
431 core in its configuration directory.
433 .BI "ABORT repeated-select-errors"
434 The main event loop is repeatedly failing. If the server doesn't quit,
435 it will probably waste all available CPU doing nothing.
437 These indicate a problem with the administration socket interface.
439 .BI "ADMIN accept-error \-\- " message
440 There was an error while attempting to accept a connection from a new
443 .BI "ADMIN client-read-error \-\- " message
444 There was an error sending data to a client. The connection to the
445 client has been closed.
446 .SS "KEYMGMT warnings"
447 These indicate a problem with the keyring files, or the keys stored in
450 .BI "KEYMGMT bad-private-key \-\- " message
451 The private key could not be read, or failed a consistency check. If
452 there was a problem with the file, usually there will have been
454 warnings before this.
456 .BI "KEYMGMT bad-public-keyring \-\- " message
457 The public keyring couldn't be read. Usually, there will have been
459 warnings before this.
461 .BI "KEYMGMT key-file-error " file ":" line " \-\- " message
462 Reports a specific error with the named keyring file. This probably
466 .BI "KEYMGMT public-key " tag " " tokens\fR...
467 These messages all indicate a problem with the public key named
470 .BI "KEYMGMT public-key " tag " algorithm-mismatch"
471 The algorithms specified on the public key don't match the ones for our
472 private key. All the peers in a network have to use the same
475 .BI "KEYMGMT public-key " tag " bad \-\- " message
476 The public key couldn't be read, or is invalid.
478 .BI "KEYMGMT public-key " tag " bad-public-group-element"
479 The public key is invalid. This may indicate a malicious attempt to
480 introduce a bogus key.
482 .BI "KEYMGMT public-key " tag " bad-algorithm-selection"
483 The algorithms listed on the public key couldn't be understood. The
484 algorithm selection attributes are probably malformed and need fixing.
486 .BI "KEYMGMT public-key " tag " incorrect-group"
487 The public key doesn't use the same group as our private key. All the
488 peers in a network have to use the same group.
490 .BI "KEYMGMT public-key " tag " not-found"
491 The public key for peer
493 wasn't in the public keyring.
495 .BI "KEYMGMT public-key " tag " unknown-type"
496 The type of the public key isn't understood. Maybe you need to upgrade
499 (Even if you do, you'll have to regenerate your keys.)
501 These indicate problems during key-exchange. Many indicate either a bug
502 in the server (either yours or the remote one), or some kind of attack
503 in progress. All name a
505 as the second token: this is the peer the packet is apparently from,
506 though it may have been sent by an attacker instead.
508 In the descriptions below,
519 .BI "KX " peer " bad-expected-reply-log"
522 uses in its protocol contain a check value which proves that the
523 challenge is honest. This message indicates that the check value
524 supplied is wrong: someone is attempting to use bogus challenges to
527 server to leak private key information. No chance!
529 .BI "KX " peer " decrypt-failed reply\fR|\fBswitch-ok"
530 A symmetrically-encrypted portion of a key-exchange message failed to
533 .BI "KX " peer " invalid " msgtoken
534 A key-exchange message was malformed. This almost certainly indicates a
537 .BI "KX " peer " incorrect cookie\fR|\fBswitch-rq\fR|\fBswitch-ok"
538 A message didn't contain the right magic data. This may be a replay of
539 some old exchange, or random packets being sent in an attempt to waste
542 .BI "KX " peer " public-key-expired"
543 The peer's public key has expired. It's maintainer should have given
544 you a replacement before now.
546 .BI "KX " peer " sending-cookie"
547 We've received too many bogus pre-challenge messages. Someone is trying
548 to flood us with key-exchange messages and make us waste CPU on doing
549 hard asymmetric crypto sums.
551 .BI "KX " peer " unexpected " msgtoken
552 The message received wasn't appropriate for this stage of the key
553 exchange process. This may mean that one of our previous packets got
556 it may simply mean that the peer has recently restarted.
558 .BI "KX " peer " unknown-challenge"
559 The peer is asking for an answer to a challenge which we don't know
560 about. This may mean that we've been inundated with challenges from
561 some malicious source
562 .I who can read our messages
563 and discarded the valid one.
565 .BI "KX " peer " unknown-message 0x" nn
566 An unknown key-exchange message arrived.
568 These are largely concerned with management of peers and the low-level
569 details of the network protocol. The second word is usually the name of
574 .BI "PEER \- unexpected-source " address\fR...
575 A packet arrived from
577 (a network address \(en see above), but no peer is known at that
578 address. This may indicate a misconfiguration, or simply be a result of
579 one end of a connection being set up before the other.
581 .BI "PEER " peer " bad-packet no-type"
582 An empty packet arrived. This is very strange.
584 .BI "PEER " peer " bad-packet unknown-category 0x" nn
587 (in hex) isn't understood. Probably a strange random packet from
588 somewhere; could be an unlikely bug.
590 .BI "PEER " peer " bad-packet unknown-type 0x" nn
593 (in hex) isn't understood. Probably a strange random packet from
594 somewhere; could be an unlikely bug.
596 .BI "PEER " peer " decrypt-failed"
597 An encrypted IP packet failed to decrypt. It may have been mangled in
598 transit, or may be a very old packet from an expired previous session
599 key. There is usually a considerable overlap in the validity periods of
600 successive session keys, so this shouldn't occur unless the key exchange
603 .BI "PEER " peer " packet-build-failed"
604 There wasn't enough space in our buffer to put the packet we wanted to
605 send. Shouldn't happen.
607 .BI "PEER \- socket-read-error \-\- " message
608 An error occurred trying to read an incoming packet.
610 .BI "PEER " peer " socket-write-error \-\- " message
611 An error occurred attempting to send a network packet. We lost that
613 .SS "SERVER warnings"
614 These indicate problems concerning the server process as a whole.
616 .BI "SERVER ignore signal " name
617 A signal arrived, but the server ignored it. Currently this happens for
619 because that's a popular way of telling daemons to re-read their
620 configuration files. Since
622 re-reads its keyrings automatically and has no other configuration
623 files, it's not relevant, but it seemed better to ignore the signal than
626 .BI "SERVER quit signal " \fR[\fInn\fR|\fIname\fR]
631 .BI "SERVER quit admin-request"
632 A client of the administration interface issued a
636 .BI "SERVER select-error \-\- " message
637 An error occurred in the server's main event loop. This is bad: if it
638 happens too many times, the server will abort.
640 These are concerned with the symmetric encryption and decryption
643 .BI "SYMM replay old-sequence"
644 A packet was received with an old sequence number. It may just have
645 been delayed or duplicated, or it may have been an attempt at a replay
648 .BI "SYMM replay duplicated-sequence"
649 A packet was received with a sequence number we've definitely seen
650 before. It may be an accidental duplication because the 'net is like
651 that, or a deliberate attempt at a replay.
653 These concern the workings of the system-specific tunnel driver. The
654 second word is the name of the tunnel interface in question, or
658 .BI "TUN \- bsd no-tunnel-devices"
659 The driver couldn't find an available tunnel device. Maybe if you
664 .BI "TUN - open-error " device " \-\- " message
665 An attempt to open the tunnel device file
669 .BI "TUN \- linux config-error \-\- " message
670 Configuring the Linux TUN/TAP interface failed.
672 .BI "TUN " ifname " read-error \-\- " message
673 Reading from the tunnel device failed.
675 .BI "TUN " ifname " slip bad-escape"
676 The SLIP driver encountered a escaped byte it wasn't expecting to see.
677 The erroneous packet will be ignored.
679 .BI "TUN " ifname " slip eof"
680 The SLIP driver encountered end-of-file on its input descriptor.
681 Pending data is discarded, and no attempt is made to read any more data
682 from that interface ever.
684 .BI "TUN " ifname " slip escape-end"
685 The SLIP driver encountered an escaped `end' marker. This probably
686 means that someone's been sending it junk. The erroneous packet is
687 discarded, and we hope that we've rediscovered synchronization.
689 .BI "TUN \- slip fork-error \-\- " message
690 The SLIP driver encountered an error forking a child process while
691 allocating a new dynamic interface.
693 .BI "TUN \- slip no-slip-interfaces"
694 The driver ran out of static SLIP interfaces. Either preallocate more,
695 or use dynamic SLIP interface allocation.
697 .BI "TUN " ifname " slip overflow"
698 The SLIP driver gave up reading a packet because it got too large.
700 .BI "TUN \- slip pipe-error \-\- " message
701 The SLIP driver encountered an error creating pipes while allocating a
702 new dynamic interface.
704 .BI "TUN \- slip read-ifname-failed \-\- " message
705 The SLIP driver encountered an error reading the name of a dynamically
706 allocated interface. Maybe the allocation script is broken.
708 .BI "TUN \- unet config-error \-\- " message
709 Configuring the Linux Unet interface failed. Unet is obsolete and
710 shouldn't be used any more.
712 .BI "TUN \- unet getinfo-error \-\- " message
713 Reading information about the Unet interface failed. Unet is obsolete
714 and shouldn't be used any more.
716 .BI "TUN \- unet ifname-too-long \-\- " message
717 The Unet interface's name overflowed, so we couldn't read it properly.
718 Unet is obsolete and shouldn't be used any more.
720 These are issued by administration clients using the
724 .BI "USER " tokens\fR...
725 An administration client issued a warning.
730 .IR "The Trivial IP Encryption Protocol" .
732 Mark Wooding, <mdw@distorted.org.uk>
~mdw / tripe / blob