X-Git-Url: https://git.distorted.org.uk/~mdw/tripe/blobdiff_plain/6411163d48434575eaf49463e056e971a2fba16a..d98625f4404ba4fca4f395bc72f15d68043d75b4:/server/tripe-admin.5.in diff --git a/server/tripe-admin.5.in b/server/tripe-admin.5.in index 5b0fe3be..43f77254 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" @@ -364,6 +363,19 @@ address and emit an .B NEWADDR notification. .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. .\"-opts @@ -375,10 +387,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 +422,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 +446,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 +454,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 +471,12 @@ 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 +\- 29 \- +.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. +octet, and the bulk-crypto transform overhead (which includes the +sequence number). .RE .SP .BI "BGCANCEL " tag @@ -460,7 +492,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. @@ -541,10 +573,43 @@ The keepalive interval, in seconds, or zero if no keepalives are to be sent. .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. .RE .SP .BI "PING \fR[" options "\fR] " peer @@ -598,12 +663,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 +716,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 +825,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 +964,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. @@ -961,6 +1036,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 +1085,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 +1126,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 +1137,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 +1145,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" @@ -1192,58 +1292,116 @@ 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. +couldn't be found in the 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.) +.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 @@ -1263,6 +1421,12 @@ is one of the tokens or .BR switch-ok . .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 .B tripe @@ -1286,9 +1450,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 @@ -1385,6 +1551,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 +1627,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.