Fix reading of timeouts

[pixie] / 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"
.SH "NAME"
pixie \- new, improved PGP passphrase pixie
.SH "SYNOPSIS"
.B pixie
.RB [ \-xqv ]
.RB [ \-t
.IR timeout ]
.RB [ \-d
.IR dir ]
.RI [ socket ]
.PP
.B pgp-pixie
.SH "DESCRIPTION"
The passphrase pixie sets up a Unix-domain socket and gives your PGP
passphrase to anyone who connects to it.  It tries quite hard to make
sure that only your own processes are allowed to do this, and to be
secure in other ways.  This is mostly useful with Ian Jackson's
.B auto-pgp
tools.
.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 "\-x, \-\-x11"
Use the
.BR xgetline (1)
program to request a passphrase when necessary, rather than requesting
the passphrase from the terminal.
.RB ( xgetline
is part of the
.B xtoys
distribution.  It requires the GTK library.)  Use the
.B +x
or
.B \-\-no\-x11
option to prevent use of
.BR xgetline .
.TP
.B "\-q, \-\-quiet"
Produce fewer messages.  This can be used multiple times to make the
pixie very quiet.
.TP
.B "\-v, \-\-verbose"
Produce more messages.  This can be used multiple times to make the
pixie more verbose.
.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
.BI "\-d, \-\-dir=" directory
Create, secure and set the named directory as being current before
creating a socket.  If the directory does not exist, it is created with
mode 700 (readable and writable only by owner); if it does exist, it is
checked to ensure that it's owned by the calling user, and it's not
readable or writable by anyone other than the caller.
.PP
If neither of
.B \-x
nor
.B +x
are specified on the command line, the pixie decides for itself how to
ask for a passphrase.  If standard input is a terminal, it uses the
terminal; otherwise it tries
.BR xgetline .
.PP
A socket name is required if no
.B \-d
option is given; otherwise it's optional and defaults to
.BR pass-socket .
.PP
The
.B pgp-pixie
shell script provides some default arguments to the main
.B pixie
program which put the socket in
.BR $PGPPATH/.wrapper/pass-socket ,
where the other
.B auto-pgp
tools expect it to be.  It passes any command line options straight on
to the main
.B pixie
program.
.SS "Pixie initialization"
The pixie initializes itself as follows:
.hP 1.
If the operating system supports locking pages into memory, the pixie
requests a page of memory and then attempts to lock it.  If successful,
the passphrase will be stored in this area of memory to prevent its
being swapped out to disk.
.hP 2.
The pixie sets its effective uid the same as its real uid, dropping any
setuid privileges the program might have had.
.hP 3.
If the attempt to lock the page failed, or the operating system doesn't
support locking pages, a buffer of normal memory is allocated for the
passphrase.
.hP 4.
The pixie parses its command line options.
.hP 5.
If a directory was specified with the
.B \-d
option, the pixie attempts to set it as the current directory.  If the
attempt fails because the directory doesn't exist, it is created and the
attempt to change directory is made again.  The directory's status is
then examined to ensure that it conforms with the security requirements
described above.
.hP 6.
A Unix domain socket is created, with the process's umask (see
.BR umask (2))
artifically set to 077.  If socket cannot be created, for whatever
reason, the pixie reports an error and exits.
.hP 7.
If the verbosity level is sufficiently high, and a locked memory page
could not be allocated, the pixie emits a warning.
.SS "Runtime behaviour"
After initialization, the pixie enters a loop, waiting for various
things to happen.
.PP
If a client connects to the pixie's socket, the pixie will write its
passphrase to the connected socket and then close it.  If the pixie
currently has no passphrase, it asks for one and starts a timer (if one
was requested by the user).
.PP
When the passphrase timer expires, all memory of the passphrase is
expunged, and the timer is removed.  Any future connections requesting a
passphrase will require the user to type one in again.
.PP
Some signals have a special meaning for the pixie:
.TP
.BR SIGINT " and " SIGTERM
Cause an orderly shutdown of the pixie.  The Unix-domain socket is
removed.
.TP
.BR SIGHUP " and " SIGQUIT
Causes the passphrase to be forgotten immediately, as if timed out.
This can be handy if you've typed the passphrase wrongly.
.RB ( SIGQUIT
was chosen because it can be easily typed at the terminal, usually using
.BR C-\e .)
.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
.B \-d
option 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
The
.BR xgetline (1)
program is not as careful about locking memory as the pixie is.
Hopefully the fact that it's a short-lived process means that this isn't
a major issue; however, it remains possible that the passphrase typed
into
.B xgetline
could be swapped to disk.
.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 pixie incorporates some improvements over the original
which were noted in the
.B auto-pgp
documentation.
.SH "AUTHOR"
Mark Wooding, <mdw@nsict.org>