5 \h'-\w'\\$1\ 'u'\\$1\ \c
11 .TH pixie 1 "14 October 1999" "Straylight/Edgeware" "Catacomb cryptographic library"
13 pixie \- Catacomb passphrase pixie
28 .RI [ "request args" ...]
36 The passphrase pixie manages passphrases. When it starts up, it creates
37 a Unix-domain socket in a private directory. Clients may connect to it
38 and request named passphrases: if the passphrase is known, the pixie
39 returns it; otherwise the pixie may (configurably) either return a
40 failure code to the client or attempt to prompt the user itself. In the
41 former case, the client program will inform the pixie of the selected
42 passphrase; in both cases, the passphrase will be remembered for later
45 Passphrases which have been stored for a long time without being used
46 are removed from memory. On systems which support it, the passphrase
47 pixie uses locked memory to prevent sensitive information from being
48 swapped out by the operating system.
50 .SS "Command-line options"
53 program understands the following command-line options:
56 Prints a relatively comprehensive help message, and exit successfully.
59 Print the pixie's version number and exit successfully.
62 Print a terse usage summary and exit successfully.
65 Connect to a running pixie as a client. If command-line arguments are
66 supplied, they are concatenated with spaces between them and submitted
67 to the pixie as a request; a reply is read from the pixie and formatted:
68 information is written to standard output; errors are reported via
69 standard error and the exit status. If no command-line arguments are
70 given, requestss are read interactively from stdin and sent to the
71 pixie; the pixie's responses are printed on stdout uninterpreted.
73 .B "\-P, \-\-passphrase"
74 Connect to a running pixie and request the passphrase with tag
76 If no pixie is running then request the passphrase from the terminal.
77 Print the result on standard output, followed by a newline.
79 .B "\-PP, \-\-verify-passphrase"
80 Connect to a running pixie and request verification of the passphrase
83 If no pixie is running, request the passphrase from the terminal. Print
84 the result on standard output, followed by a newline.
87 Causes the pixie to emit fewer log messages.
90 Causes the pixie to emit more verbose log messages.
92 .BI "\-s, \-\-socket=" socket
95 as the name of the Unix-domain socket. If running as a client, this is
96 the socket to which a connection is made. If running as a server, and
97 the socket already exists, the pixie currently listening on the socket
100 .BI "\-c, \-\-command=" command
101 Specifies a shell command to be run by the pixie when an unknown
102 passphrase is requested by a client.
105 If an unknown passphrase is requested by a client, the pixie should
106 attempt to read a passphrase itself rather than returning an error code.
108 .BI "\-t, \-\-timeout=" timeout
109 Sets a timeout for the user's passphrase. The timeout is, by default,
110 in seconds, although a suffix
115 can be added to specify minutes, hours or days respectively. A timeout
116 of zero means that the pixie will never time out a passphrase. The
117 default is to time out a passphrase after 15 minutes.
120 Fork into the background and disassociate from the terminal after
124 Send log messages to the syslog rather than stderr.
126 .SS "Memory management"
127 During initialization, the pixie attempts to allocate a block of memory
128 from the kernel and protect it against being swapped to disk. On Linux
129 and other systems with
131 or similar, this should just work assuming that the limit is set
132 sensibly. On other systems, this requires that the pixie start with
133 root privileges, although it will drop them as soon as it can (before
134 parsing command-line options, for example).
136 The locked memory is used for all of the passphrases which the pixie
137 stores, and for the buffers used to hold requests from clients.
139 .SS "The pixie socket"
140 Communication with the passphrase pixie is performed over a Unix-domain
143 If no socket name is specified on the command line, the pixie reads a
144 default from the environment variable
145 .BR CATACOMB_PIXIE_SOCKET ;
146 if that's not set, a default of
147 .RB ` %h/.catacomb/pixie '
150 The socket name may contain substitution directives
154 which are replaced by the current user's name and home directory
159 is running as a client, it will just attempt to connect to the socket.
160 If this fails, it reports an error and exits. The remainder of this
161 section deals only with the behaviour of the pixie as a server.
163 If the socket name has the form
165 then the pixie will check that
167 is a directory, creating it if it doesn't exist, and that it is not
168 readable or writable by anyone other than its owner.
170 It then attempts to create the socket, giving read and write permissions
171 only to its owner. If the attempt succeeds, the pixie's initialization
174 If the attempt failed because a file with the required name already
175 exists and is not a socket, the pixie reports an error and exits. If
176 there's already a socket with that name, the pixie connects to it, sends
179 request to the server, waits for a second and retries. If the
180 connection attempt fails because there's nobody listening, the pixie
181 assumes that the socket is stale, deletes it, and tries again.
184 The protocol used by the pixie is fairly straightforward.
186 Passphrases are known by textual
188 which are assigned by the client. A tag must not contain whitespace
189 characters. It's conventional for the tag to be lowercase or mostly
190 lowercase, and for multiple words to be joined by dashes.
192 The pixie's responses always have one of the following forms:
194 .BR OK " [\fIphrase\fR]"
195 The request completed successfully. If the request was
199 the response contains the passphrase.
202 The passphrase requested is not known. The client should request the
203 passphrase from the user itself, and then inform the pixie using the
208 The request failed. The
210 is a human-readable explanation of what went wrong.
213 Reports a human-readable informational message. Processing of the
214 request is not complete: further responses will follow.
216 .BI ITEM " tag expires"
217 Reports a passphrase as part of the response to a
221 response is given for each passphrase currently known. The
223 field names the passphrase tag, and the
225 field gives the number of seconds until the passphrase will expire.
226 Processing of the request is not complete: further responses will
229 The requests available are as follows:
232 Returns brief help on the available protocol requests.
235 Returns a list of the currently-known passphrases and their expiry
238 .BI PASS " tag \fR[\fIexpire\fR]"
239 Returns the passphrase named
241 If the passphrase is unknown, and the pixie fetches it, it should expire
242 after the timeout given by
244 using the same syntax as the
248 .BI VERIFY " tag \fR[\fIexpire\fR]"
249 Requests a new passphrase named
251 If the pixie is capable of fetching passphrases, it should ask the user
252 for confirmation to guard against typos. Otherwise this is the same as
257 .BI SET " tag \fR[\fIexpire\fR] " \-\- " phrase"
258 Sets the value of the passphrase named
262 optionally setting its expiry time to
264 This will usually be a follow-up to a
266 response. If a passphrase with the same tag is already known, it is
269 .BR FLUSH " [\fItag\fR]"
272 is given, flush that passphrase from memory. Otherwise flush
274 passphrases from memory.
277 Asks the pixie to quit.
279 Pixie requests are not case sensitive, in order to make interactive use
280 easier. The responses are guaranteed to be returned in uppercase,
283 .SS "Specifying commands"
284 If the pixie is given a
286 option, it will use the argument as a shell command in order to request
287 passphrases from the user. Before execution, the pixie will perform
288 some substitutions on the command string:
293 .RB ` "New passphrase" ',
295 .RB ` "Verify passphrase" '
299 The tag of the passphrase being requested.
301 The shell command is expected to write the passphrase to its standard
302 output, optionally followed by a newline, and exit with status 0. If it
303 returns some other exit status, the pixie will assume that it failed and
305 .SH "IMPORTANT SECURITY NOTE"
306 Don't use this software on a machine with a hostile admin. You will
307 lose. Any machine with hostile administration must be automatically
308 assumed hostile. Never type a passphrase into a hostile machine. Don't
309 sent a passphrase over a hostile or potentially hostile network. Don't
310 do anything else stupid.
312 The pixie's preinitialization checking doesn't do a thorough audit of a
313 directory, in the way that, say,
315 does. It's your responsibility to make sure that the full path is
318 It's possible, though unlikely, that there's a security hole in the part
321 program which can run with setuid privileges. In this case, remove
322 setuid privileges immediately \- the program runs quite happily without,
323 except that it might not be able to lock pages into memory.
324 .SH "ACKNOWLEDGEMENTS"
325 The original passphrase pixie was written by Ian Jackson as part of his
327 package. This version of the pixie is major evolution of one I wrote
328 for PGP which incorporated the improvements over the original which were
333 Mark Wooding, <mdw@distorted.org.uk>
projects / u / mdw / catacomb / blob