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 | . |
11 | .TH pixie 1 "14 October 1999" Catacomb |
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" ...] |
29 | .SH "DESCRIPTION" |
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 |
37 | use. |
38 | .PP |
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. |
43 | .\" |
44 | .SS "Command-line options" |
45 | The |
46 | .B pixie |
47 | program understands the following command-line options: |
48 | .TP |
49 | .B "\-h, \-\-help" |
50 | Prints a relatively comprehensive help message, and exit successfully. |
51 | .TP |
52 | .B "\-V, \-\-version" |
53 | Print the pixie's version number and exit successfully. |
54 | .TP |
55 | .B "\-u, \-\-usage" |
56 | Print a terse usage summary and exit successfully. |
57 | .TP |
58 | .B "\-C, \-\-client" |
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. |
65 | .TP |
66 | .B "\-q, \-\-quiet" |
67 | Causes the pixie to emit fewer log messages. |
68 | .TP |
69 | .B "\-v, \-\-verbose" |
70 | Causes the pixie to emit more verbose log messages. |
71 | .TP |
72 | .BI "\-s, \-\-socket=" socket |
73 | Uses |
74 | .I 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 |
78 | is told to quit. |
79 | .TP |
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. |
83 | .TP |
84 | .BI "\-f, \-\-fetch" |
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. |
87 | .TP |
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 |
91 | .RB ` m ', |
92 | .RB ` h ' |
93 | or |
94 | .RB ` d ' |
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. |
98 | .TP |
99 | .B "\-d, \-\-daemon" |
100 | Fork into the background and disassociate from the terminal after |
101 | initializing. |
102 | .TP |
103 | .B "\-l, \-\-syslog" |
104 | Send log messages to the syslog rather than stderr. |
105 | .\" |
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). |
112 | .PP |
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. |
115 | .\" |
116 | .SS "The pixie socket" |
117 | Communication with the passphrase pixie is performed over a Unix-domain |
118 | socket. |
119 | .PP |
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 ' |
125 | is used. |
126 | .PP |
127 | The socket name may contain substitution directives |
128 | .RB ` %u ' |
129 | and |
130 | .RB ` %h ', |
131 | which are replaced by the current user's name and home directory |
132 | respectively. |
133 | .PP |
134 | If |
135 | .B pixie |
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. |
139 | .PP |
140 | If the socket name has the form |
141 | .IB dir / name |
142 | then the pixie will check that |
143 | .I dir |
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. |
146 | .PP |
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 |
149 | is complete. |
150 | .PP |
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 |
154 | a |
155 | .B QUIT |
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. |
159 | .\" |
160 | .SS "Pixie protocol" |
161 | The protocol used by the pixie is fairly straightforward. |
162 | .PP |
163 | Passphrases are known by textual |
164 | .I tags |
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. |
168 | .PP |
169 | The pixie's responses always have one of the following forms: |
170 | .TP |
171 | .BR OK " [\fIphrase\fR]" |
172 | The request completed successfully. If the request was |
173 | .B PASS |
174 | or |
175 | .BR VERIFY , |
176 | the response contains the passphrase. |
177 | .TP |
178 | .B MISSING |
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 |
181 | .B SET |
182 | request. |
183 | .TP |
184 | .BI FAIL " error" |
185 | The request failed. The |
186 | .I error |
187 | is a human-readable explanation of what went wrong. |
188 | .TP |
189 | .BI INFO " message" |
190 | Reports a human-readable informational message. Processing of the |
191 | request is not complete: further responses will follow. |
192 | .TP |
193 | .BI ITEM " tag expires" |
194 | Reports a passphrase as part of the response to a |
195 | .B LIST |
196 | request. One |
197 | .B ITEM |
198 | response is given for each passphrase currently known. The |
199 | .I tag |
200 | field names the passphrase tag, and the |
201 | .I expires |
202 | field gives the number of seconds until the passphrase will expire. |
203 | Processing of the request is not complete: further responses will |
204 | follow. |
205 | .PP |
206 | The requests available are as follows: |
207 | .TP |
208 | .B HELP |
209 | Returns brief help on the available protocol requests. |
210 | .TP |
211 | .B LIST |
212 | Returns a list of the currently-known passphrases and their expiry |
213 | information. |
214 | .TP |
215 | .BI PASS " tag \fR[\fIexpire\fR]" |
216 | Returns the passphrase named |
217 | .IR tag . |
218 | If the passphrase is unknown, and the pixie fetches it, it should expire |
219 | after the timeout given by |
220 | .IR expire , |
221 | using the same syntax as the |
222 | .B \-t |
223 | command-line option. |
224 | .TP |
225 | .B VERIFY " tag \fR[\fIexpire\fR]" |
226 | Requests a new passphrase named |
227 | .IR tag . |
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 |
230 | the |
231 | .B PASS |
232 | request. |
233 | .TP |
234 | .BI SET "tag \fR[\fIexpire\fR] " \-\- " phrase" |
235 | Sets the value of the passphrase named |
236 | .I tag |
237 | to be |
238 | .IR phrase , |
239 | optionally setting its expiry time to |
240 | .IR expire . |
241 | This will usually be a follow-up to a |
242 | .B MISSING |
243 | response. If a passphrase with the same tag is already known, it is |
244 | removed. |
245 | .TP |
246 | .BR FLUSH " [\fItag\fR]" |
247 | If a |
248 | .I tag |
249 | is given, flush that passphrase from memory. Otherwise flush |
250 | .I all |
251 | passphrases from memory. |
252 | .TP |
253 | .B QUIT |
254 | Asks the pixie to quit. |
255 | .PP |
256 | Pixie requests are not case sensitive, in order to make interactive use |
257 | easier. The responses are guaranteed to be returned in uppercase, |
258 | however. |
259 | .\" |
260 | .SS "Specifying commands" |
261 | If the pixie is given a |
262 | .B \-c |
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: |
266 | .TP |
267 | .B %m |
268 | One of |
269 | .RB ` Passphrase ', |
270 | .RB ` "New passphrase" ', |
271 | or |
272 | .RB ` "Verify passphrase" ' |
273 | as appropriate. |
274 | .TP |
275 | .B %t |
276 | The tag of the passphrase being requested. |
277 | .PP |
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 |
281 | ignore its output. |
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. |
288 | .SH "OTHER CAVEATS" |
289 | The pixie's preinitialization checking doesn't do a thorough audit of a |
290 | directory, in the way that, say |
291 | .BR chkpath (1) |
292 | does. It's your responsibility to make sure that the full path is |
293 | relatively safe. |
294 | .PP |
295 | It's possible, though unlikely, that there's a security hole in the part |
296 | of the |
297 | .B pixie |
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 |
303 | .B auto-pgp |
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 |
306 | noted in the |
307 | .B auto-pgp |
308 | documentation. |
309 | .SH "AUTHOR" |
310 | Mark Wooding, <mdw@nsict.org> |