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 .B "\-r, \-\-replace"
101 If there's already a pixie listening on the socket then ask it to quit.
102 The default behaviour is to report an error and exit in this case.
104 .BI "\-c, \-\-command=" command
105 Specifies a shell command to be run by the pixie when an unknown
106 passphrase is requested by a client.
109 If an unknown passphrase is requested by a client, the pixie should
110 attempt to read a passphrase itself rather than returning an error code.
112 .BI "\-t, \-\-timeout=" timeout
113 Sets a timeout for the user's passphrase. The timeout is, by default,
114 in seconds, although a suffix
119 can be added to specify minutes, hours or days respectively. A timeout
120 of zero means that the pixie will never time out a passphrase. The
121 default is to time out a passphrase after 15 minutes.
124 Fork into the background and disassociate from the terminal after
128 Send log messages to the syslog rather than stderr.
130 .SS "Memory management"
131 During initialization, the pixie attempts to allocate a block of memory
132 from the kernel and protect it against being swapped to disk. On Linux
133 and other systems with
135 or similar, this should just work assuming that the limit is set
136 sensibly. On other systems, this requires that the pixie start with
137 root privileges, although it will drop them as soon as it can (before
138 parsing command-line options, for example).
140 The locked memory is used for all of the passphrases which the pixie
141 stores, and for the buffers used to hold requests from clients.
143 .SS "The pixie socket"
144 Communication with the passphrase pixie is performed over a Unix-domain
147 If no socket name is specified on the command line, the pixie reads a
148 default from the environment variable
149 .BR CATACOMB_PIXIE_SOCKET ;
150 if that's not set, a default of
151 .RB ` %h/.catacomb/pixie '
154 The socket name may contain substitution directives
158 which are replaced by the current user's name and home directory
163 is running as a client, it will just attempt to connect to the socket.
164 If this fails, it reports an error and exits. The remainder of this
165 section deals only with the behaviour of the pixie as a server.
167 If the socket name has the form
169 then the pixie will check that
171 is a directory, creating it if it doesn't exist, and that it is not
172 readable or writable by anyone other than its owner.
174 It then attempts to create the socket, giving read and write permissions
175 only to its owner. If the attempt succeeds, the pixie's initialization
178 If the attempt failed because a file with the required name already
179 exists and is not a socket, the pixie reports an error and exits. If
180 there's already a socket with that name, the pixie quits unless the
182 option is given: in the latter case, the pixie connects to it, sends
185 request to the server, waits for a second and retries. If the
186 connection attempt fails because there's nobody listening, the pixie
187 assumes that the socket is stale, deletes it, and tries again.
190 The protocol used by the pixie is fairly straightforward.
192 Passphrases are known by textual
194 which are assigned by the client. A tag must not contain whitespace
195 characters. It's conventional for the tag to be lowercase or mostly
196 lowercase, and for multiple words to be joined by dashes.
198 The pixie's responses always have one of the following forms:
200 .BR OK " [\fIphrase\fR]"
201 The request completed successfully. If the request was
205 the response contains the passphrase.
208 The passphrase requested is not known. The client should request the
209 passphrase from the user itself, and then inform the pixie using the
214 The request failed. The
216 is a human-readable explanation of what went wrong.
219 Reports a human-readable informational message. Processing of the
220 request is not complete: further responses will follow.
222 .BI ITEM " tag expires"
223 Reports a passphrase as part of the response to a
227 response is given for each passphrase currently known. The
229 field names the passphrase tag, and the
231 field gives the number of seconds until the passphrase will expire.
232 Processing of the request is not complete: further responses will
235 The requests available are as follows:
238 Returns brief help on the available protocol requests.
241 Returns a list of the currently-known passphrases and their expiry
244 .BI PASS " tag \fR[\fIexpire\fR]"
245 Returns the passphrase named
247 If the passphrase is unknown, and the pixie fetches it, it should expire
248 after the timeout given by
250 using the same syntax as the
254 .BI VERIFY " tag \fR[\fIexpire\fR]"
255 Requests a new passphrase named
257 If the pixie is capable of fetching passphrases, it should ask the user
258 for confirmation to guard against typos. Otherwise this is the same as
263 .BI SET " tag \fR[\fIexpire\fR] " \-\- " phrase"
264 Sets the value of the passphrase named
268 optionally setting its expiry time to
270 This will usually be a follow-up to a
272 response. If a passphrase with the same tag is already known, it is
275 .BR FLUSH " [\fItag\fR]"
278 is given, flush that passphrase from memory. Otherwise flush
280 passphrases from memory.
283 Asks the pixie to quit.
285 Pixie requests are not case sensitive, in order to make interactive use
286 easier. The responses are guaranteed to be returned in uppercase,
289 .SS "Specifying commands"
290 If the pixie is given a
292 option, it will use the argument as a shell command in order to request
293 passphrases from the user. Before execution, the pixie will perform
294 some substitutions on the command string:
299 .RB ` "New passphrase" ',
301 .RB ` "Verify passphrase" '
305 The tag of the passphrase being requested.
307 The shell command is expected to write the passphrase to its standard
308 output, optionally followed by a newline, and exit with status 0. If it
309 returns some other exit status, the pixie will assume that it failed and
311 .SH "IMPORTANT SECURITY NOTE"
312 Don't use this software on a machine with a hostile admin. You will
313 lose. Any machine with hostile administration must be automatically
314 assumed hostile. Never type a passphrase into a hostile machine. Don't
315 sent a passphrase over a hostile or potentially hostile network. Don't
316 do anything else stupid.
318 The pixie's preinitialization checking doesn't do a thorough audit of a
319 directory, in the way that, say,
321 does. It's your responsibility to make sure that the full path is
324 It's possible, though unlikely, that there's a security hole in the part
327 program which can run with setuid privileges. In this case, remove
328 setuid privileges immediately \- the program runs quite happily without,
329 except that it might not be able to lock pages into memory.
330 .SH "ACKNOWLEDGEMENTS"
331 The original passphrase pixie was written by Ian Jackson as part of his
333 package. This version of the pixie is major evolution of one I wrote
334 for PGP which incorporated the improvements over the original which were
339 Mark Wooding, <mdw@distorted.org.uk>
projects / u / mdw / catacomb / blob