5 \h'-\w'\\$1\ 'u'\\$1\ \c
11 .TH pixie 1 "14 October 1999"
13 pixie \- new, improved PGP passphrase pixie
25 The passphrase pixie sets up a Unix-domain socket and gives your PGP
26 passphrase to anyone who connects to it. It tries quite hard to make
27 sure that only your own processes are allowed to do this, and to be
28 secure in other ways. This is mostly useful with Ian Jackson's
31 .SS "Command line options"
34 program understands the following command line options:
37 Prints a relatively comprehensive help message, and exit successfully.
40 Print the pixie's version number and exit successfully.
43 Print a terse usage summary and exit successfully.
48 program to request a passphrase when necessary, rather than requesting
49 the passphrase from the terminal.
53 distribution. It requires the GTK library.) Use the
57 option to prevent use of
61 Produce fewer messages. This can be used multiple times to make the
65 Produce more messages. This can be used multiple times to make the
68 .BI "\-t, \-\-timeout=" timeout
69 Sets a timeout for the user's passphrase. The timeout is, by default,
70 in seconds, although a suffix
75 can be added to specify minutes, hours or days respectively. A timeout
76 of zero means that the pixie will never time out a passphrase. The
77 default is to time out a passphrase after 5 minutes.
79 .BI "\-d, \-\-dir=" directory
80 Create, secure and set the named directory as being current before
81 creating a socket. If the directory does not exist, it is created with
82 mode 700 (readable and writable only by owner); if it does exist, it is
83 checked to ensure that it's owned by the calling user, and it's not
84 readable or writable by anyone other than the caller.
90 are specified on the command line, the pixie decides for itself how to
91 ask for a passphrase. If standard input is a terminal, it uses the
92 terminal; otherwise it tries
95 A socket name is required if no
97 option is given; otherwise it's optional and defaults to
102 shell script provides some default arguments to the main
104 program which put the socket in
105 .BR $PGPPATH/.wrapper/pass-socket ,
108 tools expect it to be. It passes any command line options straight on
112 .SS "Pixie initialization"
113 The pixie initializes itself as follows:
115 If the operating system supports locking pages into memory, the pixie
116 requests a page of memory and then attempts to lock it. If successful,
117 the passphrase will be stored in this area of memory to prevent its
118 being swapped out to disk.
120 The pixie sets its effective uid the same as its real uid, dropping any
121 setuid privileges the program might have had.
123 If the attempt to lock the page failed, or the operating system doesn't
124 support locking pages, a buffer of normal memory is allocated for the
127 The pixie parses its command line options.
129 If a directory was specified with the
131 option, the pixie attempts to set it as the current directory. If the
132 attempt fails because the directory doesn't exist, it is created and the
133 attempt to change directory is made again. The directory's status is
134 then examined to ensure that it conforms with the security requirements
137 A Unix domain socket is created, with the process's umask (see
139 artifically set to 077. If socket cannot be created, for whatever
140 reason, the pixie reports an error and exits.
142 If the verbosity level is sufficiently high, and a locked memory page
143 could not be allocated, the pixie emits a warning.
144 .SS "Runtime behaviour"
145 After initialization, the pixie enters a loop, waiting for various
148 If a client connects to the pixie's socket, the pixie will write its
149 passphrase to the connected socket and then close it. If the pixie
150 currently has no passphrase, it asks for one and starts a timer (if one
151 was requested by the user).
153 When the passphrase timer expires, all memory of the passphrase is
154 expunged, and the timer is removed. Any future connections requesting a
155 passphrase will require the user to type one in again.
157 Some signals have a special meaning for the pixie:
159 .BR SIGINT " and " SIGTERM
160 Cause an orderly shutdown of the pixie. The Unix-domain socket is
163 .BR SIGHUP " and " SIGQUIT
164 Causes the passphrase to be forgotten immediately, as if timed out.
165 This can be handy if you've typed the passphrase wrongly.
167 was chosen because it can be easily typed at the terminal, usually using
169 .SH "IMPORTANT SECURITY NOTE"
170 Don't use this software on a machine with a hostile admin. You will
171 lose. Any machine with hostile administration must be automatically
172 assumed hostile. Never type a passphrase into a hostile machine. Don't
173 sent a passphrase over a hostile or potentially hostile network. Don't
174 do anything else stupid.
178 option doesn't do a thorough audit of a directory, in the way that, say
180 does. It's your responsibility to make sure that the full path is
185 program is not as careful about locking memory as the pixie is.
186 Hopefully the fact that it's a short-lived process means that this isn't
187 a major issue; however, it remains possible that the passphrase typed
190 could be swapped to disk.
192 It's possible, though unlikely, that there's a security hole in the part
195 program which can run with setuid privileges. In this case, remove
196 setuid privileges immediately \- the program runs quite happily without,
197 except that it might not be able to lock pages into memory.
198 .SH "ACKNOWLEDGEMENTS"
199 The original passphrase pixie was written by Ian Jackson as part of his
201 package. This pixie incorporates some improvements over the original
202 which were noted in the
206 Mark Wooding, <mdw@nsict.org>
~mdw / pixie / blob