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 most
129 systems, this requires that the pixie start with root privileges,
130 although it will drop them as soon as it can (before parsing
131 command-line options).
133 The locked memory is used for all of the passphrases which the pixie
134 stores, and for the buffers used to hold requests from clients.
136 .SS "The pixie socket"
137 Communication with the passphrase pixie is performed over a Unix-domain
140 If no socket name is specified on the command line, the pixie reads a
141 default from the environment variable
142 .BR CATACOMB_PIXIE_SOCKET ;
143 if that's not set, a default of
144 .RB ` %h/.catacomb/pixie '
147 The socket name may contain substitution directives
151 which are replaced by the current user's name and home directory
156 is running as a client, it will just attempt to connect to the socket.
157 If this fails, it reports an error and exits. The remainder of this
158 section deals only with the behaviour of the pixie as a server.
160 If the socket name has the form
162 then the pixie will check that
164 is a directory, creating it if it doesn't exist, and that it is not
165 readable or writable by anyone other than its owner.
167 It then attempts to create the socket, giving read and write permissions
168 only to its owner. If the attempt succeeds, the pixie's initialization
171 If the attempt failed because a file with the required name already
172 exists and is not a socket, the pixie reports an error and exits. If
173 there's already a socket with that name, the pixie connects to it, sends
176 request to the server, waits for a second and retries. If the
177 connection attempt fails because there's nobody listening, the pixie
178 assumes that the socket is stale, deletes it, and tries again.
181 The protocol used by the pixie is fairly straightforward.
183 Passphrases are known by textual
185 which are assigned by the client. A tag must not contain whitespace
186 characters. It's conventional for the tag to be lowercase or mostly
187 lowercase, and for multiple words to be joined by dashes.
189 The pixie's responses always have one of the following forms:
191 .BR OK " [\fIphrase\fR]"
192 The request completed successfully. If the request was
196 the response contains the passphrase.
199 The passphrase requested is not known. The client should request the
200 passphrase from the user itself, and then inform the pixie using the
205 The request failed. The
207 is a human-readable explanation of what went wrong.
210 Reports a human-readable informational message. Processing of the
211 request is not complete: further responses will follow.
213 .BI ITEM " tag expires"
214 Reports a passphrase as part of the response to a
218 response is given for each passphrase currently known. The
220 field names the passphrase tag, and the
222 field gives the number of seconds until the passphrase will expire.
223 Processing of the request is not complete: further responses will
226 The requests available are as follows:
229 Returns brief help on the available protocol requests.
232 Returns a list of the currently-known passphrases and their expiry
235 .BI PASS " tag \fR[\fIexpire\fR]"
236 Returns the passphrase named
238 If the passphrase is unknown, and the pixie fetches it, it should expire
239 after the timeout given by
241 using the same syntax as the
245 .BI VERIFY " tag \fR[\fIexpire\fR]"
246 Requests a new passphrase named
248 If the pixie is capable of fetching passphrases, it should ask the user
249 for confirmation to guard against typos. Otherwise this is the same as
254 .BI SET " tag \fR[\fIexpire\fR] " \-\- " phrase"
255 Sets the value of the passphrase named
259 optionally setting its expiry time to
261 This will usually be a follow-up to a
263 response. If a passphrase with the same tag is already known, it is
266 .BR FLUSH " [\fItag\fR]"
269 is given, flush that passphrase from memory. Otherwise flush
271 passphrases from memory.
274 Asks the pixie to quit.
276 Pixie requests are not case sensitive, in order to make interactive use
277 easier. The responses are guaranteed to be returned in uppercase,
280 .SS "Specifying commands"
281 If the pixie is given a
283 option, it will use the argument as a shell command in order to request
284 passphrases from the user. Before execution, the pixie will perform
285 some substitutions on the command string:
290 .RB ` "New passphrase" ',
292 .RB ` "Verify passphrase" '
296 The tag of the passphrase being requested.
298 The shell command is expected to write the passphrase to its standard
299 output, optionally followed by a newline, and exit with status 0. If it
300 returns some other exit status, the pixie will assume that it failed and
302 .SH "IMPORTANT SECURITY NOTE"
303 Don't use this software on a machine with a hostile admin. You will
304 lose. Any machine with hostile administration must be automatically
305 assumed hostile. Never type a passphrase into a hostile machine. Don't
306 sent a passphrase over a hostile or potentially hostile network. Don't
307 do anything else stupid.
309 The pixie's preinitialization checking doesn't do a thorough audit of a
310 directory, in the way that, say,
312 does. It's your responsibility to make sure that the full path is
315 It's possible, though unlikely, that there's a security hole in the part
318 program which can run with setuid privileges. In this case, remove
319 setuid privileges immediately \- the program runs quite happily without,
320 except that it might not be able to lock pages into memory.
321 .SH "ACKNOWLEDGEMENTS"
322 The original passphrase pixie was written by Ian Jackson as part of his
324 package. This version of the pixie is major evolution of one I wrote
325 for PGP which incorporated the improvements over the original which were
330 Mark Wooding, <mdw@distorted.org.uk>
projects / u / mdw / catacomb / blob