X-Git-Url: https://git.distorted.org.uk/~mdw/tripe/blobdiff_plain/6411163d48434575eaf49463e056e971a2fba16a..acd781a81901f9785125ea2c4c99d5d0952eecdd:/server/tripe-admin.5.in diff --git a/server/tripe-admin.5.in b/server/tripe-admin.5.in index 5b0fe3be..698e2a69 100644 --- a/server/tripe-admin.5.in +++ b/server/tripe-admin.5.in @@ -9,25 +9,24 @@ .\" .\" This file is part of Trivial IP Encryption (TrIPE). .\" -.\" TrIPE is free software; you can redistribute it and/or modify -.\" it under the terms of the GNU General Public License as published by -.\" the Free Software Foundation; either version 2 of the License, or -.\" (at your option) any later version. +.\" TrIPE is free software: you can redistribute it and/or modify it under +.\" the terms of the GNU General Public License as published by the Free +.\" Software Foundation; either version 3 of the License, or (at your +.\" option) any later version. .\" -.\" TrIPE is distributed in the hope that it will be useful, -.\" but WITHOUT ANY WARRANTY; without even the implied warranty of -.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.\" GNU General Public License for more details. +.\" TrIPE is distributed in the hope that it will be useful, but WITHOUT +.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +.\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. .\" .\" You should have received a copy of the GNU General Public License -.\" along with TrIPE; if not, write to the Free Software Foundation, -.\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. +.\" along with TrIPE. If not, see . . .\"-------------------------------------------------------------------------- .so ../common/defs.man \" @@@PRE@@@ . .\"-------------------------------------------------------------------------- -.TH tripe-admin 5 "18 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption" +.TH tripe-admin 5tripe "18 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption" . .\"-------------------------------------------------------------------------- .SH "NAME" @@ -252,21 +251,50 @@ the meanings of the subsequent tokens depend on the address family. Address family tokens are not case-sensitive on input; on output, they are always in upper-case. .PP -At present, only one address family is understood. +The following address families are recognized. +.TP +.BI "ANY " address " \fR[" port \fR] +An address and port number for any supported address family. On output, +.B tripe +never uses this form. On input, the +.I address +is examined: if it is a numeric address for some recognized address +family, then it is interpreted as such; otherwise it is looked up using +the DNS (in the background). The background resolver's address-sorting +rules apply, and +.B tripe +simply takes the first address in the returned list which is of a +supported address family. Symbolic port numbers are permitted; if +omitted, the default port 4070 is used. .TP .BI "INET " address " \fR[" port \fR] An Internet socket, naming an IPv4 address and UDP port. On output, the -address is always in numeric dotted-quad form, and the port is given as -a plain number. On input, DNS hostnames and symbolic port names are -permitted; if omitted, the default port 4070 is used. Name resolution -does not block the main server, but will block the requesting client, -unless the command is run in the background. +.I address +is always in numeric dotted-quad form, and the +.I port +is given as a plain decimal number. On input, DNS hostnames and +symbolic port names are permitted; if omitted, the default port 4070 is +used. +.TP +.BI "INET6 " address " \fR[" port \fR] +An Internet socket, naming an IPv6 address and UDP port. On output, the +.I address +is always in numeric hex-and-colons form, and the +.I port +is given as a plain decimal number. On input, DNS hostnames and +symbolic port names may be permitted, depending on how +.B tripe +was compiled; if omitted, the default port 4070 is used. .PP If, on input, no recognized address family token is found, the following tokens are assumed to represent an -.B INET +.B ANY address. Addresses output by the server always have an address family -token. +token, and do not use +.BR ANY . +.PP +Name resolution never blocks the main server, but will block the +requesting client, unless the command is run in the background. .SS "Key-value output" Some commands (e.g., .B STATS @@ -333,6 +361,21 @@ Run the command in the background, using the given Don't send an immediate challenge to the peer; instead, wait until it sends us something before responding. .TP +.B "\-ephemeral" +The association with the peer is not intended to persist indefinitely. +If a peer marked as ephemeral is killed, or the +.BR tripe (8) +daemon is shut down, send a +.B bye +packet to the peer so that it forgets about us; if a peer marked as +ephemeral sends us a +.B bye +packet then it is killed (but in this case no further +.B bye +packet is sent). Peers not marked as ephemeral exhibit neither of these +behaviours; each peer must have the other marked as ephemeral for the +association to be fully torn down if either end kills the other. +.TP .BI "\-keepalive " time Send a no-op packet if we've not sent a packet to the peer in the last .I time @@ -354,6 +397,26 @@ Use the public key to authenticate the peer. The default is to use the key tagged .IR peer . .TP +.BI "\-knock \fR[" prefix .\fR] tag +Send the string +.RI [ prefix\fB. ] tag +in +.B token-rq +and +.B knock +messages to the peer during key-exchange. The string as a whole should +name the local machine to the peer, and +.I tag +should name its public key. When such messages are received from a +currently unknown peer, +.BR tripe (8) +emits a +.B KNOCK +notification stating the peer's (claimed) name and address. The server +will already have verified that the sender is using the peer's private +key by this point. This option implies +.BR \-ephemeral . +.TP .B "\-mobile" The peer is a mobile device, and is likely to change address rapidly. If a packet arrives from an unknown address, the server's usual response @@ -362,7 +425,21 @@ peers, however, it will attempt to decrypt the packet using their keys, and if one succeeds, the server will update its idea of the peer's address and emit an .B NEWADDR -notification. +notification. This option implies +.BR \-ephemeral . +.TP +.BI "\-priv " tag +Use the private key +.I tag +to authenticate to the peer. The default is to use the key named in the +.RB ` \-t ' +command-line option, or a key with type +.B tripe +or +.BR tripe-dh : +see +.BR tripe (8) +for the details. .TP .BI "\-tunnel " tunnel Use the named tunnel driver, rather than the default. @@ -375,10 +452,15 @@ Emits an line reporting the IP address and port number stored for .IR peer . .SP -.B "ALGS" +.BI "ALGS \fR[" peer \fR] Emits information about the cryptographic algorithms in use, in -key-value form. The keys are as follows. +key-value form. If a +.I peer +is given, then describe the algorithms used in the association with that +peer; otherwise describe the default algorithms. .RS +.PP +The keys are as follows. .TP .B kx-group Type of key-exchange group in use, currently either @@ -405,6 +487,12 @@ The mask-generating function in use, e.g., .B hashsz The size of the hash function's output, in octets. .TP +.B bulk-transform +The name of the bulk-crypto transform. +.TP +.B bulk-overhead +The amount of overhead, in bytes, caused by the crypto transform. +.TP .B cipher The name of the bulk data cipher in use, e.g., .BR blowfish-cbc . @@ -423,7 +511,7 @@ allow for a seamless changeover of keys.) .TP .B mac The message authentication algorithm in use, e.g., -.BR ripemd160-hmac .. +.BR ripemd160-hmac . .TP .B mac-keysz The length of the key used by the message authentication algorithm, in @@ -431,6 +519,16 @@ octets. .TP .B mac-tagsz The length of the message authentication tag, in octets. +.TP +.B blkc +The block cipher in use, e.g., +.BR blowfish . +.TP +.B blkc-keysz +The length of key used by the block cipher, in octets. +.TP +.B blkc-blksz +The block size of the block cipher. .PP The various sizes are useful, for example, when computing the MTU for a tunnel interface. If @@ -438,13 +536,16 @@ tunnel interface. If is the MTU of the path to the peer, then the tunnel MTU should be .IP .I MTU -\- 33 \- -.I cipher-blksz \- -.I mac-tagsz +.I header-length +\- 9 \- +.I bulk-overhead .PP -allowing 20 bytes of IP header, 8 bytes of UDP header, a packet type -octet, a four-octet sequence number, an IV, and a MAC tag. +allowing +.I header-length += 20 (IPv4) or 40 (IPv6) bytes of IP header, 8 bytes of UDP header, a +packet type octet, and the bulk-crypto transform overhead (which +includes the sequence number). .RE .SP .BI "BGCANCEL " tag @@ -460,7 +561,7 @@ or in a greeting message. .SP .B "DAEMON" Causes the server to disassociate itself from its terminal and become a -background task. This only works once. A warning is issued. +background task. This only works once. A notification is issued. .SP .BI "EPING \fR[" options "\fR] " peer Sends an encrypted ping to the peer, and expects an encrypted response. @@ -540,11 +641,62 @@ The tunnel driver used for this peer. The keepalive interval, in seconds, or zero if no keepalives are to be sent. .TP +.B knock +If present, the string sent to the peer to set up the association; see +the +.B \-knock +option to +.BR ADD , +and the +.B KNOCK +notification. +.TP .B key -The key tag being used for the peer, as passed to the +The (short) key tag being used for the peer, as passed to the +.B ADD +command. +.TP +.B current-key +The full key tag of the peer's public key currently being used. This +may change during the life of the association. +.TP +.B private-key +The private key tag being used for the peer, as passed to the .B ADD -command. (You don't get a full key-id, since that might change while -the daemon's running.) +command, or the +.RB ` \-t ' +command-line option. If neither of these was given explicitly, the +private key tag is shown as +.RB ` (default) ', +since there is no fixed tag used under these circumstances. +.TP +.B current-private-key +The full key tag of the private key currently being used for this +association. This may change during the life of the association. +.TP +.B corked +Either +.B t +or +.B nil +depending on whether or not (respectively) key-exchange is waiting for +the peer to initiate. +.TP +.B mobile +Either +.B t +or +.B nil +depending on whether or not (respectively) the peer is expected to +change its address unpredictably. +.TP +.B ephemeral +Either +.B t +or +.B nil +depending on whether the association with the peer is expected to be +temporary or persistent (respectively). .RE .SP .BI "PING \fR[" options "\fR] " peer @@ -598,12 +750,18 @@ given, seconds are assumed. .RE .SP .B "PORT" +.RI [ family ] Emits an .B INFO line containing just the number of the UDP port used by the .B tripe -server. If you've allowed your server to allocate a port dynamically, -this is how to find out which one it chose. +server, for the given address +.I family +(or one chosen arbitrarily if omitted -- though +.B tripe +tries to use the same port number consistently so this is not a likely +problem in practice). If you've allowed your server to allocate a port +dynamically, this is how to find out which one it chose. .SP .B "RELOAD" Instructs the server to recheck its keyring files. The server checks @@ -645,6 +803,13 @@ This is useful if firewalling decisions are made based on interface names: a setup script for a particular peer can change the name, and then update the server's records so that they're accurate. .SP +.BI "STATS " peer +Emits a number of +.B INFO +lines, each containing one or more statistics in the form +.IB name = value \fR. +The statistics-gathering is experimental and subject to change. +.SP .BI "SVCCLAIM " service " " version Attempts to claim the named .IR service , @@ -747,13 +912,6 @@ of the service is available before submitting the job. .RE .\"-opts .SP -.BI "STATS " peer -Emits a number of -.B INFO -lines, each containing one or more statistics in the form -.IB name = value \fR. -The statistics-gathering is experimental and subject to change. -.SP .BR "TRACE " [\fIoptions\fP] Selects trace outputs: see .B "Trace lists" @@ -893,6 +1051,10 @@ server is already running as a daemon. (For commands accepting socket addresses.) The address couldn't be understood. .SP +.BI "bad-base64 " message +(For commands accepting Base64-encoded input.) The Base64-encoded +string was invalid. +.SP .BI "bad-syntax " cmd " " message (For any command.) The command couldn't be understood: e.g., the number of arguments was wrong. @@ -925,6 +1087,15 @@ An unknown watch option was requested. An error occurred during the attempt to become a daemon, as reported by .IR message . .SP +.BI "disabled-address-family " afam +(For +.B ADD +and +.BR PORT .) +The address family +.I afam +is supported, but was disabled using command-line arguments. +.SP .BI "invalid-port " number (For .BR ADD .) @@ -961,6 +1132,17 @@ There is already a peer named The attempt to send a ping packet failed, probably due to lack of encryption keys. .SP +.B "provider-failed" +(For +.BR SVCSUBMIT .) +The service provider disconnected without sending back a final reply to +the job. +.SP +.B "provider-overloaded" +(For +.BR SVCSUBMIT .) +The service provider has too many jobs queued up for it already. +.SP .BI "resolve-error " hostname (For .BR ADD .) @@ -999,6 +1181,13 @@ is available, which does not meet the stated requirements. .I tag is already the tag of an outstanding job. .SP +.BI "unknown-address-family " afam +(For +.BR PORT .) +The address family +.I afam +is unrecognized. +.SP .BI "unknown-command " token The command .I token @@ -1033,7 +1222,7 @@ The port name .I port couldn't be found in .BR /etc/services . -.TP +.SP .BI "unknown-service " service (For .BR SVCENSURE , @@ -1044,7 +1233,7 @@ and The token .I service is not recognized as the name of a client-provided service. -.TP +.SP .BI "unknown-tag " tag (For .BR BGCANCEL .) @@ -1052,6 +1241,13 @@ The given .I tag is not the tag for any outstanding background job. It may have just finished. +.SP +.BI "unknown-tunnel " tun +(For +.BR ADD .) +The given +.I tun +is not the name of any known tunnel driver. . .\"-------------------------------------------------------------------------- .SH "NOTIFICATIONS" @@ -1081,6 +1277,12 @@ The peer .I peer has been killed. .SP +.BI "KNOCK " peer " " address +The currently unknown +.I peer +is attempting to connect from +.IR address . +.SP .BI "KXDONE " peer Key exchange with .I peer @@ -1192,58 +1394,121 @@ up to something! Challenge received was old, but maybe not actually a replay. Try again. .SS "KEYMGMT warnings" These indicate a problem with the keyring files, or the keys stored in -them. -.SP -.BI "KEYMGMT bad-private-key " message -The private key could not be read, or failed a consistency check. If -there was a problem with the file, usually there will have been -.B key-file-error -warnings before this. -.SP -.BI "KEYMGMT bad-public-keyring " message -The public keyring couldn't be read. Usually, there will have been -.B key-file-error -warnings before this. -.SP -.BI "KEYMGMT key-file-error " file ":" line " " message -Reports a specific error with the named keyring file. This probably -indicates a bug in -.BR key (1). -.SP -.BI "KEYMGMT public-key " tag " " tokens\fR... -These messages all indicate a problem with the public key named -.IR tag . -.SP -.BI "KEYMGMT public-key " tag " algorithm-mismatch" -The algorithms specified on the public key don't match the ones for our -private key. All the peers in a network have to use the same -algorithms. -.SP -.BI "KEYMGMT public-key " tag " bad " message -The public key couldn't be read, or is invalid. -.SP -.BI "KEYMGMT public-key " tag " bad-public-group-element" -The public key is invalid. This may indicate a malicious attempt to -introduce a bogus key. -.SP -.BI "KEYMGMT public-key " tag " bad-algorithm-selection" -The algorithms listed on the public key couldn't be understood. The -algorithm selection attributes are probably malformed and need fixing. +them. The first token is either +.B private-keyring +or +.B public-keyring +(notated +.IB which -keyring +in the descriptions below) indicating which keyring file is problematic, +and the second token is the filename of the keyring. Frequently a key +tag may be given next, preceded by the token +.BR key . +.SP +.BI "KEYMGMT private-keyring " file " key " tag " incorrect-public-key" +The private key doesn't record the correct corresponding public key. +.SP +.BI "KEYMGMT public-keyring " file " key " tag " algorithm-mismatch" +A peer's public key doesn't request the same algorithms as our private +key. +.SP +.BI "KEYMGMT " which "-keyring " file " key " tag " bad-tag-length " len +The key attributes specify the length of MAC tag as +.I len +but this is an invalid value \(en either too large or not a multiple of +eight. +.SP +.BI "KEYMGMT " which "-keyring " file " key " tag " bad-tag-length-string " str +The key attributes contain +.I str +where a MAC tag length was expected. The key was generated wrongly. +.SP +.BI "KEYMGMT private-keyring " file " key " tag " changed-group" +The private keyring has been changed, but the new private key can't be +used because it uses a different group for Diffie\(enHellman key +exchange. +.SP +.BI "KEYMGMT " which "-keyring " file " io-error " ecode " " message +A system error occurred while opening or reading the keyring file. +.SP +.BI "KEYMGMT " which "-keyring " file " key " tag " unknown-bulk-transform " bulk +The key specifies the use of an unknown bulk-crypto transform +.IR bulk . +Maybe the key was generated wrongly, or maybe the version of Catacomb +installed is too old. +.SP +.BI "KEYMGMT " which "-keyring " file " key " tag " unknown-cipher " cipher +The key specifies the use of an unknown symmetric encryption algorithm +.IR cipher . +Maybe the key was generated wrongly, or maybe the version of +Catacomb installed is too old. +.SP +.BI "KEYMGMT " which "-keyring " file " key " tag " unknown-group-type " type +The key specifies the use of a Diffie\(enHellman group of an unknown +.IR type . +Maybe the key was generated wrongly, or maybe the version of +.BR tripe (8) +is too old. +.SP +.BI "KEYMGMT " which "-keyring " file " key " tag " unknown-hash " hash +The key specifies the use of an unknown hash function +.IR hash . +Maybe the key was generated wrongly, or maybe the version of Catacomb +installed is too old. +.SP +.BI "KEYMGMT " which "-keyring " file " key " tag " unknown-mac " mac +The key specifies the use of an unknown message authentication code +.IR mac . +Maybe the key was generated wrongly, or maybe the version of Catacomb +installed is too old. +.SP +.BI "KEYMGMT " which "-keyring " file " key " tag " unknown-mgf-cipher " mgf +The key specifies the use of an unknown symmetric encryption function +.I mgf +for mask generation. Maybe the key was generated wrongly, or maybe the +version of Catacomb installed is too old. +.SP +.BI "KEYMGMT " which "-keyring " file " key " tag " unknown-serialization-format " ser +The key specifies the use of an unknown serialization format +.I ser +for hashing group elements. Maybe the key was generated wrongly, or +maybe the version of Catacomb installed is too old. +.SP +.BI "KEYMGMT " which "-keyring " file " key " tag " no-hmac-for-hash " hash +No message authentication code was given explicitly, and there's no +implementation of HMAC for the selected hash function +.IR hash . +.SP +.BI "KEYMGMT " which "-keyring " file " key " tag " " alg " " name " no-key-size " hashsz +The +.I alg +token is either +.B cipher +or +.BR mac . +The named algorithm requires more key material than the hash function +can provide. You must change either the hash function, or the cipher or +MAC. .SP -.BI "KEYMGMT public-key " tag " incorrect-group" -The public key doesn't use the same group as our private key. All the -peers in a network have to use the same group. +.BI "KEYMGMT " which "-keyring " file " key " tag " mgf " mgf " restrictive-key-schedule" +The cipher selected for mask-generation is unsuitable because it can't +accept arbitrary-sized keys. .SP -.BI "KEYMGMT public-key " tag " not-found" -The public key for peer +.BI "KEYMGMT " which "-keyring " file " key-not-found " tag +A key named .I tag -wasn't in the public keyring. -.SP -.BI "KEYMGMT public-key " tag " unknown-type" -The type of the public key isn't understood. Maybe you need to upgrade -your copy of -.BR tripe . -(Even if you do, you'll have to regenerate your keys.) +couldn't be found in the keyring. +.SP +.BI "KEYMGMT " which "-keyring " file " unknown-key-id 0x" keyid +A key with the given +.I keyid +(in hex) was requested but not found. +.SP +.BI "KEYMGMT " which "-keyring " file " line " line " " message +The contents of the keyring file are invalid. There may well be a bug +in the +.BR key (1) +program. .SS "KX warnings" These indicate problems during key-exchange. Many indicate either a bug in the server (either yours or the remote one), or some kind of attack @@ -1260,8 +1525,17 @@ is one of the tokens .BR challenge , .BR reply , .BR switch-rq , -or .BR switch-ok . +.BR token-rq , +.BR token , +or +.BR knock . +.SP +.BI "KX " peer " algorithms-mismatch local-private-key " privtag " peer-public-key " pubtag +The algorithms specified in the peer's public key +.I pubtag +don't match the ones described in the private key +.IR privtag . .SP .BI "KX " peer " bad-expected-reply-log" The challenges @@ -1286,9 +1560,11 @@ A message didn't contain the right magic data. This may be a replay of some old exchange, or random packets being sent in an attempt to waste CPU. .SP -.BI "KX " peer " public-key-expired" -The peer's public key has expired. It's maintainer should have given -you a replacement before now. +.BI "KX " peer " " which "-key-expired" +The local private key or the peer's public key (distinguished by +.IR which ) +has expired. Either you or the peer's maintainer should have arranged +for a replacement before now. .SP .BI "KX " peer " sending-cookie" We've received too many bogus pre-challenge messages. Someone is trying @@ -1368,6 +1644,14 @@ An error occurred trying to read an incoming packet. An error occurred attempting to send a network packet. We lost that one. .SP +.BI "PEER " address\fR... " disabled-address-family" +An attempt was made to send a packet to an address for which support was +switched off by command-line options. +.SP +.BI "PEER " address\fR... " socket-write-error " ecode " " message +An error occurred attempting to send a network packet. We lost that +one. +.SP .BI "PEER " peer " unexpected-encrypted-ping 0x" id The peer sent an encrypted ping response whose id doesn't match any outstanding ping. Maybe it was delayed for longer than the server was @@ -1385,6 +1669,51 @@ The peer (apparently) sent a transport ping response whose id doesn't match any outstanding ping. Maybe it was delayed for longer than the server was willing to wait, or maybe the peer has gone mad; or maybe there are bad people trying to confuse you. +.SS "PRIVSEP warnings" +These indicate problems with the privilege-separation helper process. +(The server tries to drop its privileges when it starts up, leaving a +privileged helper process behind which will create and hand over tunnel +descriptors on request, but hopefully not do anything else especially +dangerous. Tunnel descriptors are not completely safe, but this is +probably better than nothing.) +.SP +.BI "PRIVSEP child-exited " rc +The helper process exited normally with status +.IR rc . +Status 0 means that it thought the server didn't want it any more; 1 +means that it was invoked incorrectly; 127 means that some system call +failed. +.SP +.BI "PRIVSEP child-killed " sig +The helper process was killed by signal number +.IR sig . +.SP +.BI "PRIVSEP child-died " status +The helper process died in some unexpected way; +.I status is the raw status code returned by +.BR waitpid (2), +because the server didn't understand how to decode it. +.SP +.BI "PRIVSEP helper-died" +A tunnel driver requires a tunnel descriptor from the helper, but the +helper isn't running so this won't work. +.SP +.BI "PRIVSEP helper-read-error " ecode " " message +The server failed to read a response from the helper process. +.SP +.BI "PRIVSEP helper-short-read" +The helper process didn't send back enough data, and has likely crashed. +.SP +.BI "PRIVSEP helper-write-error " ecode " " message +The server failed to send a message to the helper process. +.SP +.BI "PRIVSEP no-fd-from-helper" +The helper process sent back a positive response, but didn't include the +requested tunnel descriptor. +.SP +.BI "PRIVSEP unknown-response-code" +The helper process sent back an incomprehensible reply. It's probably +very confused and may crash. .SS "SERVER warnings" These indicate problems concerning the server process as a whole. .SP @@ -1416,6 +1745,10 @@ option), and encountered end-of-file on standard input. .BI "SERVER select-error " ecode " " message An error occurred in the server's main event loop. This is bad: if it happens too many times, the server will abort. +.SP +.BI "SERVER waitpid-error " ecode " " message +The server was informed that one of its child processes had exited, but +couldn't retrieve the child's status. .SS "SYMM warnings" These are concerned with the symmetric encryption and decryption process.