From d92b3cee9432cfb30b85acd42ed4b4f8dc48b4d7 Mon Sep 17 00:00:00 2001 From: mdw Date: Sat, 29 Jul 2000 21:58:28 +0000 Subject: [PATCH] New manpage for the Catacomb pixie. --- pixie.1 | 310 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 310 insertions(+) create mode 100644 pixie.1 diff --git a/pixie.1 b/pixie.1 new file mode 100644 index 0000000..38f542c --- /dev/null +++ b/pixie.1 @@ -0,0 +1,310 @@ +.\" -*-nroff-*- +.de hP +.IP +.ft B +\h'-\w'\\$1\ 'u'\\$1\ \c +.ft P +.. +.ie t .ds o \(bu +.el .ds o o +. +.TH pixie 1 "14 October 1999" Catacomb +.SH "NAME" +pixie \- Catacomb passphrase pixie +.SH "SYNOPSIS" +.B pixie +.RB [ \-qvfidl ] +.RB [ \-c +.IR command ] +.RB [ \-t +.IR timeout ] +.RB [ \-s +.IR socket ] +.br +.B pixie +.RB [ \-s +.IR socket ] +.B \-C +.RI [ "request args" ...] +.SH "DESCRIPTION" +The passphrase pixie manages passphrases. When it starts up, it creates +a Unix-domain socket in a private directory. Clients may connect to it +and request named passphrases: if the passphrase is known, the pixie +returns it; otherwise the pixie may (configurably) either return a +failure code to the client or attempt to prompt the user itself. In the +former case, the client program will inform the pixie of the selected +passphrase; in both cases, the passphrase will be remembered for later +use. +.PP +Passphrases which have been stored for a long time without being used +are removed from memory. On systems which support it, the passphrase +pixie uses locked memory to prevent sensitive information from being +swapped out by the operating system. +.\" +.SS "Command-line options" +The +.B pixie +program understands the following command-line options: +.TP +.B "\-h, \-\-help" +Prints a relatively comprehensive help message, and exit successfully. +.TP +.B "\-V, \-\-version" +Print the pixie's version number and exit successfully. +.TP +.B "\-u, \-\-usage" +Print a terse usage summary and exit successfully. +.TP +.B "\-C, \-\-client" +Connect to a running pixie as a client. If command-line arguments are +supplied, they are concatenated with spaces between them and submitted +to the pixie as a request; a reply is read from the pixie and printed +on stdout. If no command-line arguments are given, requestss are read +interactively from stdin and sent to the pixie; the pixie's responses +are printed on stdout. +.TP +.B "\-q, \-\-quiet" +Causes the pixie to emit fewer log messages. +.TP +.B "\-v, \-\-verbose" +Causes the pixie to emit more verbose log messages. +.TP +.BI "\-s, \-\-socket=" socket +Uses +.I socket +as the name of the Unix-domain socket. If running as a client, this is +the socket to which a connection is made. If running as a server, and +the socket already exists, the pixie currently listening on the socket +is told to quit. +.TP +.BI "\-c, \-\-command=" command +Specifies a shell command to be run by the pixie when an unknown +passphrase is requested by a client. +.TP +.BI "\-f, \-\-fetch" +If an unknown passphrase is requested by a client, the pixie should +attempt to read a passphrase itself rather than returning an error code. +.TP +.BI "\-t, \-\-timeout=" timeout +Sets a timeout for the user's passphrase. The timeout is, by default, +in seconds, although a suffix +.RB ` m ', +.RB ` h ' +or +.RB ` d ' +can be added to specify minutes, hours or days respectively. A timeout +of zero means that the pixie will never time out a passphrase. The +default is to time out a passphrase after 5 minutes. +.TP +.B "\-d, \-\-daemon" +Fork into the background and disassociate from the terminal after +initializing. +.TP +.B "\-l, \-\-syslog" +Send log messages to the syslog rather than stderr. +.\" +.SS "Memory management" +During initialization, the pixie attempts to allocate a block of memory +from the kernel and protect it against being swapped to disk. On most +systems, this requires that the pixie start with root privileges, +although it will drop them as soon as it can (before parsing +command-line options). +.PP +The locked memory is used for all of the passphrases which the pixie +stores, and for the buffers used to hold requests from clients. +.\" +.SS "The pixie socket" +Communication with the passphrase pixie is performed over a Unix-domain +socket. +.PP +If no socket name is specified on the command line, the pixie reads a +default from the environment variable +.BR CATACOMB_PIXIE_SOCKET ; +if that's not set, a default of +.RB ` %h/.catacomb/pixie ' +is used. +.PP +The socket name may contain substitution directives +.RB ` %u ' +and +.RB ` %h ', +which are replaced by the current user's name and home directory +respectively. +.PP +If +.B pixie +is running as a client, it will just attempt to connect to the socket. +If this fails, it reports an error and exits. The remainder of this +section deals only with the behaviour of the pixie as a server. +.PP +If the socket name has the form +.IB dir / name +then the pixie will check that +.I dir +is a directory, creating it if it doesn't exist, and that it is not +readable or writable by anyone other than its owner. +.PP +It then attempts to create the socket, giving read and write permissions +only to its owner. If the attempt succeeds, the pixie's initialization +is complete. +.PP +If the attempt failed because a file with the required name already +exists and is not a socket, the pixie reports an error and exits. If +there's already a socket with that name, the pixie connects to it, sends +a +.B QUIT +request to the server, waits for a second and retries. If the +connection attempt fails because there's nobody listening, the pixie +assumes that the socket is stale, deletes it, and tries again. +.\" +.SS "Pixie protocol" +The protocol used by the pixie is fairly straightforward. +.PP +Passphrases are known by textual +.I tags +which are assigned by the client. A tag must not contain whitespace +characters. It's conventional for the tag to be lowercase or mostly +lowercase, and for multiple words to be joined by dashes. +.PP +The pixie's responses always have one of the following forms: +.TP +.BR OK " [\fIphrase\fR]" +The request completed successfully. If the request was +.B PASS +or +.BR VERIFY , +the response contains the passphrase. +.TP +.B MISSING +The passphrase requested is not known. The client should request the +passphrase from the user itself, and then inform the pixie using the +.B SET +request. +.TP +.BI FAIL " error" +The request failed. The +.I error +is a human-readable explanation of what went wrong. +.TP +.BI INFO " message" +Reports a human-readable informational message. Processing of the +request is not complete: further responses will follow. +.TP +.BI ITEM " tag expires" +Reports a passphrase as part of the response to a +.B LIST +request. One +.B ITEM +response is given for each passphrase currently known. The +.I tag +field names the passphrase tag, and the +.I expires +field gives the number of seconds until the passphrase will expire. +Processing of the request is not complete: further responses will +follow. +.PP +The requests available are as follows: +.TP +.B HELP +Returns brief help on the available protocol requests. +.TP +.B LIST +Returns a list of the currently-known passphrases and their expiry +information. +.TP +.BI PASS " tag \fR[\fIexpire\fR]" +Returns the passphrase named +.IR tag . +If the passphrase is unknown, and the pixie fetches it, it should expire +after the timeout given by +.IR expire , +using the same syntax as the +.B \-t +command-line option. +.TP +.B VERIFY " tag \fR[\fIexpire\fR]" +Requests a new passphrase named +.IR tag . +If the pixie is capable of fetching passphrases, it should ask the user +for confirmation to guard against typos. Otherwise this is the same as +the +.B PASS +request. +.TP +.BI SET "tag \fR[\fIexpire\fR] " \-\- " phrase" +Sets the value of the passphrase named +.I tag +to be +.IR phrase , +optionally setting its expiry time to +.IR expire . +This will usually be a follow-up to a +.B MISSING +response. If a passphrase with the same tag is already known, it is +removed. +.TP +.BR FLUSH " [\fItag\fR]" +If a +.I tag +is given, flush that passphrase from memory. Otherwise flush +.I all +passphrases from memory. +.TP +.B QUIT +Asks the pixie to quit. +.PP +Pixie requests are not case sensitive, in order to make interactive use +easier. The responses are guaranteed to be returned in uppercase, +however. +.\" +.SS "Specifying commands" +If the pixie is given a +.B \-c +option, it will use the argument as a shell command in order to request +passphrases from the user. Before execution, the pixie will perform +some substitutions on the command string: +.TP +.B %m +One of +.RB ` Passphrase ', +.RB ` "New passphrase" ', +or +.RB ` "Verify passphrase" ' +as appropriate. +.TP +.B %t +The tag of the passphrase being requested. +.PP +The shell command is expected to write the passphrase to its standard +output, optionally followed by a newline, and exit with status 0. If it +returns some other exit status, the pixie will assume that it failed and +ignore its output. +.SH "IMPORTANT SECURITY NOTE" +Don't use this software on a machine with a hostile admin. You will +lose. Any machine with hostile administration must be automatically +assumed hostile. Never type a passphrase into a hostile machine. Don't +sent a passphrase over a hostile or potentially hostile network. Don't +do anything else stupid. +.SH "OTHER CAVEATS" +The pixie's preinitialization checking doesn't do a thorough audit of a +directory, in the way that, say +.BR chkpath (1) +does. It's your responsibility to make sure that the full path is +relatively safe. +.PP +It's possible, though unlikely, that there's a security hole in the part +of the +.B pixie +program which can run with setuid privileges. In this case, remove +setuid privileges immediately \- the program runs quite happily without, +except that it might not be able to lock pages into memory. +.SH "ACKNOWLEDGEMENTS" +The original passphrase pixie was written by Ian Jackson as part of his +.B auto-pgp +package. This version of the pixie is major evolution of one I wrote +for PGP which incorporated the improvements over the original which were +noted in the +.B auto-pgp +documentation. +.SH "AUTHOR" +Mark Wooding, -- 2.11.0