d92b3cee |
1 | .\" -*-nroff-*- |
2 | .de hP |
3 | .IP |
4 | .ft B |
5 | \h'-\w'\\$1\ 'u'\\$1\ \c |
6 | .ft P |
7 | .. |
8 | .ie t .ds o \(bu |
9 | .el .ds o o |
10 | . |
d07dfe80 |
11 | .TH pixie 1 "14 October 1999" "Straylight/Edgeware" "Catacomb cryptographic library" |
d92b3cee |
12 | .SH "NAME" |
13 | pixie \- Catacomb passphrase pixie |
14 | .SH "SYNOPSIS" |
15 | .B pixie |
16 | .RB [ \-qvfidl ] |
17 | .RB [ \-c |
18 | .IR command ] |
19 | .RB [ \-t |
20 | .IR timeout ] |
21 | .RB [ \-s |
22 | .IR socket ] |
23 | .br |
24 | .B pixie |
25 | .RB [ \-s |
26 | .IR socket ] |
27 | .B \-C |
28 | .RI [ "request args" ...] |
025c5f4a |
29 | .br |
30 | .B pixie |
31 | .RB [ \-s |
32 | .IR socket ] |
33 | .BR \-P [ P ] |
34 | .I tag |
d92b3cee |
35 | .SH "DESCRIPTION" |
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 |
43 | use. |
44 | .PP |
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. |
49 | .\" |
50 | .SS "Command-line options" |
51 | The |
52 | .B pixie |
53 | program understands the following command-line options: |
54 | .TP |
55 | .B "\-h, \-\-help" |
56 | Prints a relatively comprehensive help message, and exit successfully. |
57 | .TP |
58 | .B "\-V, \-\-version" |
59 | Print the pixie's version number and exit successfully. |
60 | .TP |
61 | .B "\-u, \-\-usage" |
62 | Print a terse usage summary and exit successfully. |
63 | .TP |
64 | .B "\-C, \-\-client" |
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 |
025c5f4a |
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. |
72 | .TP |
73 | .B "\-P, \-\-passphrase" |
74 | Connect to a running pixie and request the passphrase with tag |
75 | .IR 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. |
78 | .TP |
79 | .B "\-PP, \-\-verify-passphrase" |
80 | Connect to a running pixie and request verification of the passphrase |
81 | with tag |
82 | .IR tag . |
83 | If no pixie is running, request the passphrase from the terminal. Print |
84 | the result on standard output, followed by a newline. |
d92b3cee |
85 | .TP |
86 | .B "\-q, \-\-quiet" |
87 | Causes the pixie to emit fewer log messages. |
88 | .TP |
89 | .B "\-v, \-\-verbose" |
90 | Causes the pixie to emit more verbose log messages. |
91 | .TP |
92 | .BI "\-s, \-\-socket=" socket |
93 | Uses |
94 | .I 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 |
98 | is told to quit. |
99 | .TP |
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. |
103 | .TP |
104 | .BI "\-f, \-\-fetch" |
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. |
107 | .TP |
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 |
111 | .RB ` m ', |
112 | .RB ` h ' |
113 | or |
114 | .RB ` d ' |
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 |
2b511ad9 |
117 | default is to time out a passphrase after 15 minutes. |
d92b3cee |
118 | .TP |
119 | .B "\-d, \-\-daemon" |
120 | Fork into the background and disassociate from the terminal after |
121 | initializing. |
122 | .TP |
123 | .B "\-l, \-\-syslog" |
124 | Send log messages to the syslog rather than stderr. |
125 | .\" |
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). |
132 | .PP |
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. |
135 | .\" |
136 | .SS "The pixie socket" |
137 | Communication with the passphrase pixie is performed over a Unix-domain |
138 | socket. |
139 | .PP |
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 ' |
145 | is used. |
146 | .PP |
147 | The socket name may contain substitution directives |
148 | .RB ` %u ' |
149 | and |
150 | .RB ` %h ', |
151 | which are replaced by the current user's name and home directory |
152 | respectively. |
153 | .PP |
154 | If |
155 | .B pixie |
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. |
159 | .PP |
160 | If the socket name has the form |
161 | .IB dir / name |
162 | then the pixie will check that |
163 | .I dir |
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. |
166 | .PP |
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 |
169 | is complete. |
170 | .PP |
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 |
174 | a |
175 | .B QUIT |
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. |
179 | .\" |
180 | .SS "Pixie protocol" |
181 | The protocol used by the pixie is fairly straightforward. |
182 | .PP |
183 | Passphrases are known by textual |
184 | .I tags |
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. |
188 | .PP |
189 | The pixie's responses always have one of the following forms: |
190 | .TP |
191 | .BR OK " [\fIphrase\fR]" |
192 | The request completed successfully. If the request was |
193 | .B PASS |
194 | or |
195 | .BR VERIFY , |
196 | the response contains the passphrase. |
197 | .TP |
198 | .B MISSING |
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 |
201 | .B SET |
202 | request. |
203 | .TP |
204 | .BI FAIL " error" |
205 | The request failed. The |
206 | .I error |
207 | is a human-readable explanation of what went wrong. |
208 | .TP |
209 | .BI INFO " message" |
210 | Reports a human-readable informational message. Processing of the |
211 | request is not complete: further responses will follow. |
212 | .TP |
213 | .BI ITEM " tag expires" |
214 | Reports a passphrase as part of the response to a |
215 | .B LIST |
216 | request. One |
217 | .B ITEM |
218 | response is given for each passphrase currently known. The |
219 | .I tag |
220 | field names the passphrase tag, and the |
221 | .I expires |
222 | field gives the number of seconds until the passphrase will expire. |
223 | Processing of the request is not complete: further responses will |
224 | follow. |
225 | .PP |
226 | The requests available are as follows: |
227 | .TP |
228 | .B HELP |
229 | Returns brief help on the available protocol requests. |
230 | .TP |
231 | .B LIST |
232 | Returns a list of the currently-known passphrases and their expiry |
233 | information. |
234 | .TP |
235 | .BI PASS " tag \fR[\fIexpire\fR]" |
236 | Returns the passphrase named |
237 | .IR tag . |
238 | If the passphrase is unknown, and the pixie fetches it, it should expire |
239 | after the timeout given by |
240 | .IR expire , |
241 | using the same syntax as the |
242 | .B \-t |
243 | command-line option. |
244 | .TP |
2b511ad9 |
245 | .BI VERIFY " tag \fR[\fIexpire\fR]" |
d92b3cee |
246 | Requests a new passphrase named |
247 | .IR tag . |
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 |
250 | the |
251 | .B PASS |
252 | request. |
253 | .TP |
2b511ad9 |
254 | .BI SET " tag \fR[\fIexpire\fR] " \-\- " phrase" |
d92b3cee |
255 | Sets the value of the passphrase named |
256 | .I tag |
257 | to be |
258 | .IR phrase , |
259 | optionally setting its expiry time to |
260 | .IR expire . |
261 | This will usually be a follow-up to a |
262 | .B MISSING |
263 | response. If a passphrase with the same tag is already known, it is |
264 | removed. |
265 | .TP |
266 | .BR FLUSH " [\fItag\fR]" |
267 | If a |
268 | .I tag |
269 | is given, flush that passphrase from memory. Otherwise flush |
270 | .I all |
271 | passphrases from memory. |
272 | .TP |
273 | .B QUIT |
274 | Asks the pixie to quit. |
275 | .PP |
276 | Pixie requests are not case sensitive, in order to make interactive use |
277 | easier. The responses are guaranteed to be returned in uppercase, |
278 | however. |
279 | .\" |
280 | .SS "Specifying commands" |
281 | If the pixie is given a |
282 | .B \-c |
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: |
286 | .TP |
287 | .B %m |
288 | One of |
289 | .RB ` Passphrase ', |
290 | .RB ` "New passphrase" ', |
291 | or |
292 | .RB ` "Verify passphrase" ' |
293 | as appropriate. |
294 | .TP |
295 | .B %t |
296 | The tag of the passphrase being requested. |
297 | .PP |
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 |
301 | ignore its output. |
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. |
308 | .SH "OTHER CAVEATS" |
309 | The pixie's preinitialization checking doesn't do a thorough audit of a |
2b511ad9 |
310 | directory, in the way that, say, |
d92b3cee |
311 | .BR chkpath (1) |
312 | does. It's your responsibility to make sure that the full path is |
313 | relatively safe. |
314 | .PP |
315 | It's possible, though unlikely, that there's a security hole in the part |
316 | of the |
317 | .B pixie |
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 |
323 | .B auto-pgp |
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 |
326 | noted in the |
327 | .B auto-pgp |
328 | documentation. |
329 | .SH "AUTHOR" |
330 | Mark Wooding, <mdw@nsict.org> |