5 \h'-\w'\\$1\ 'u'\\$1\ \c
11 .TH pixie 1 "14 October 1999" Catacomb
13 pixie \- Catacomb passphrase pixie
28 .RI [ "request args" ...]
30 The passphrase pixie manages passphrases. When it starts up, it creates
31 a Unix-domain socket in a private directory. Clients may connect to it
32 and request named passphrases: if the passphrase is known, the pixie
33 returns it; otherwise the pixie may (configurably) either return a
34 failure code to the client or attempt to prompt the user itself. In the
35 former case, the client program will inform the pixie of the selected
36 passphrase; in both cases, the passphrase will be remembered for later
39 Passphrases which have been stored for a long time without being used
40 are removed from memory. On systems which support it, the passphrase
41 pixie uses locked memory to prevent sensitive information from being
42 swapped out by the operating system.
44 .SS "Command-line options"
47 program understands the following command-line options:
50 Prints a relatively comprehensive help message, and exit successfully.
53 Print the pixie's version number and exit successfully.
56 Print a terse usage summary and exit successfully.
59 Connect to a running pixie as a client. If command-line arguments are
60 supplied, they are concatenated with spaces between them and submitted
61 to the pixie as a request; a reply is read from the pixie and printed
62 on stdout. If no command-line arguments are given, requestss are read
63 interactively from stdin and sent to the pixie; the pixie's responses
64 are printed on stdout.
67 Causes the pixie to emit fewer log messages.
70 Causes the pixie to emit more verbose log messages.
72 .BI "\-s, \-\-socket=" socket
75 as the name of the Unix-domain socket. If running as a client, this is
76 the socket to which a connection is made. If running as a server, and
77 the socket already exists, the pixie currently listening on the socket
80 .BI "\-c, \-\-command=" command
81 Specifies a shell command to be run by the pixie when an unknown
82 passphrase is requested by a client.
85 If an unknown passphrase is requested by a client, the pixie should
86 attempt to read a passphrase itself rather than returning an error code.
88 .BI "\-t, \-\-timeout=" timeout
89 Sets a timeout for the user's passphrase. The timeout is, by default,
90 in seconds, although a suffix
95 can be added to specify minutes, hours or days respectively. A timeout
96 of zero means that the pixie will never time out a passphrase. The
97 default is to time out a passphrase after 5 minutes.
100 Fork into the background and disassociate from the terminal after
104 Send log messages to the syslog rather than stderr.
106 .SS "Memory management"
107 During initialization, the pixie attempts to allocate a block of memory
108 from the kernel and protect it against being swapped to disk. On most
109 systems, this requires that the pixie start with root privileges,
110 although it will drop them as soon as it can (before parsing
111 command-line options).
113 The locked memory is used for all of the passphrases which the pixie
114 stores, and for the buffers used to hold requests from clients.
116 .SS "The pixie socket"
117 Communication with the passphrase pixie is performed over a Unix-domain
120 If no socket name is specified on the command line, the pixie reads a
121 default from the environment variable
122 .BR CATACOMB_PIXIE_SOCKET ;
123 if that's not set, a default of
124 .RB ` %h/.catacomb/pixie '
127 The socket name may contain substitution directives
131 which are replaced by the current user's name and home directory
136 is running as a client, it will just attempt to connect to the socket.
137 If this fails, it reports an error and exits. The remainder of this
138 section deals only with the behaviour of the pixie as a server.
140 If the socket name has the form
142 then the pixie will check that
144 is a directory, creating it if it doesn't exist, and that it is not
145 readable or writable by anyone other than its owner.
147 It then attempts to create the socket, giving read and write permissions
148 only to its owner. If the attempt succeeds, the pixie's initialization
151 If the attempt failed because a file with the required name already
152 exists and is not a socket, the pixie reports an error and exits. If
153 there's already a socket with that name, the pixie connects to it, sends
156 request to the server, waits for a second and retries. If the
157 connection attempt fails because there's nobody listening, the pixie
158 assumes that the socket is stale, deletes it, and tries again.
161 The protocol used by the pixie is fairly straightforward.
163 Passphrases are known by textual
165 which are assigned by the client. A tag must not contain whitespace
166 characters. It's conventional for the tag to be lowercase or mostly
167 lowercase, and for multiple words to be joined by dashes.
169 The pixie's responses always have one of the following forms:
171 .BR OK " [\fIphrase\fR]"
172 The request completed successfully. If the request was
176 the response contains the passphrase.
179 The passphrase requested is not known. The client should request the
180 passphrase from the user itself, and then inform the pixie using the
185 The request failed. The
187 is a human-readable explanation of what went wrong.
190 Reports a human-readable informational message. Processing of the
191 request is not complete: further responses will follow.
193 .BI ITEM " tag expires"
194 Reports a passphrase as part of the response to a
198 response is given for each passphrase currently known. The
200 field names the passphrase tag, and the
202 field gives the number of seconds until the passphrase will expire.
203 Processing of the request is not complete: further responses will
206 The requests available are as follows:
209 Returns brief help on the available protocol requests.
212 Returns a list of the currently-known passphrases and their expiry
215 .BI PASS " tag \fR[\fIexpire\fR]"
216 Returns the passphrase named
218 If the passphrase is unknown, and the pixie fetches it, it should expire
219 after the timeout given by
221 using the same syntax as the
225 .B VERIFY " tag \fR[\fIexpire\fR]"
226 Requests a new passphrase named
228 If the pixie is capable of fetching passphrases, it should ask the user
229 for confirmation to guard against typos. Otherwise this is the same as
234 .BI SET "tag \fR[\fIexpire\fR] " \-\- " phrase"
235 Sets the value of the passphrase named
239 optionally setting its expiry time to
241 This will usually be a follow-up to a
243 response. If a passphrase with the same tag is already known, it is
246 .BR FLUSH " [\fItag\fR]"
249 is given, flush that passphrase from memory. Otherwise flush
251 passphrases from memory.
254 Asks the pixie to quit.
256 Pixie requests are not case sensitive, in order to make interactive use
257 easier. The responses are guaranteed to be returned in uppercase,
260 .SS "Specifying commands"
261 If the pixie is given a
263 option, it will use the argument as a shell command in order to request
264 passphrases from the user. Before execution, the pixie will perform
265 some substitutions on the command string:
270 .RB ` "New passphrase" ',
272 .RB ` "Verify passphrase" '
276 The tag of the passphrase being requested.
278 The shell command is expected to write the passphrase to its standard
279 output, optionally followed by a newline, and exit with status 0. If it
280 returns some other exit status, the pixie will assume that it failed and
282 .SH "IMPORTANT SECURITY NOTE"
283 Don't use this software on a machine with a hostile admin. You will
284 lose. Any machine with hostile administration must be automatically
285 assumed hostile. Never type a passphrase into a hostile machine. Don't
286 sent a passphrase over a hostile or potentially hostile network. Don't
287 do anything else stupid.
289 The pixie's preinitialization checking doesn't do a thorough audit of a
290 directory, in the way that, say
292 does. It's your responsibility to make sure that the full path is
295 It's possible, though unlikely, that there's a security hole in the part
298 program which can run with setuid privileges. In this case, remove
299 setuid privileges immediately \- the program runs quite happily without,
300 except that it might not be able to lock pages into memory.
301 .SH "ACKNOWLEDGEMENTS"
302 The original passphrase pixie was written by Ian Jackson as part of his
304 package. This version of the pixie is major evolution of one I wrote
305 for PGP which incorporated the improvements over the original which were
310 Mark Wooding, <mdw@nsict.org>
projects / u / mdw / catacomb / blob