.gitignore: Ignore `auto-version' script.

[u/mdw/catacomb] / pixie.1

.\" -*-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" "Straylight/Edgeware" "Catacomb cryptographic library"
.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" ...]
.br
.B pixie
.RB [ \-s
.IR socket ]
.BR \-P [ P ]
.I tag
.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 formatted:
information is written to standard output; errors are reported via
standard error and the exit status.  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 uninterpreted.
.TP
.B "\-P, \-\-passphrase"
Connect to a running pixie and request the passphrase with tag
.IR tag .
If no pixie is running then request the passphrase from the terminal.
Print the result on standard output, followed by a newline.
.TP
.B "\-PP, \-\-verify-passphrase"
Connect to a running pixie and request verification of the passphrase
with tag
.IR tag .
If no pixie is running, request the passphrase from the terminal.  Print
the result on standard output, followed by a newline.
.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 15 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
.BI 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@distorted.org.uk>