+++ /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" "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 Linux
-and other systems with
-.B RLIMIT_MEMLOCK
-or similar, this should just work assuming that the limit is set
-sensibly. On other 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, for example).
-.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>
projects / u / mdw / catacomb / blobdiff