.\" -*-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,