--- /dev/null
+.\" -*-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, <mdw@nsict.org>
projects / u / mdw / catacomb / commitdiff