Commit | Line | Data |
---|---|---|
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 | |
902cbb33 | 16 | .RB [ \-qvfidlr ] |
d92b3cee | 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 | |
45c0fd36 | 81 | with tag |
025c5f4a | 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 | |
902cbb33 MW |
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. | |
103 | .TP | |
d92b3cee | 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. | |
107 | .TP | |
108 | .BI "\-f, \-\-fetch" | |
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. | |
111 | .TP | |
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 | |
115 | .RB ` m ', | |
116 | .RB ` h ' | |
117 | or | |
118 | .RB ` d ' | |
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 | |
2b511ad9 | 121 | default is to time out a passphrase after 15 minutes. |
d92b3cee | 122 | .TP |
123 | .B "\-d, \-\-daemon" | |
124 | Fork into the background and disassociate from the terminal after | |
125 | initializing. | |
126 | .TP | |
127 | .B "\-l, \-\-syslog" | |
128 | Send log messages to the syslog rather than stderr. | |
129 | .\" | |
130 | .SS "Memory management" | |
131 | During initialization, the pixie attempts to allocate a block of memory | |
5d01b1b9 MW |
132 | from the kernel and protect it against being swapped to disk. On Linux |
133 | and other systems with | |
134 | .B RLIMIT_MEMLOCK | |
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). | |
d92b3cee | 139 | .PP |
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. | |
142 | .\" | |
143 | .SS "The pixie socket" | |
144 | Communication with the passphrase pixie is performed over a Unix-domain | |
145 | socket. | |
146 | .PP | |
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 ' | |
152 | is used. | |
153 | .PP | |
154 | The socket name may contain substitution directives | |
155 | .RB ` %u ' | |
156 | and | |
157 | .RB ` %h ', | |
158 | which are replaced by the current user's name and home directory | |
159 | respectively. | |
160 | .PP | |
161 | If | |
162 | .B pixie | |
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. | |
166 | .PP | |
167 | If the socket name has the form | |
168 | .IB dir / name | |
169 | then the pixie will check that | |
170 | .I dir | |
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. | |
173 | .PP | |
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 | |
176 | is complete. | |
177 | .PP | |
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 | |
902cbb33 MW |
180 | there's already a socket with that name, the pixie quits unless the |
181 | .B \-\-replace | |
182 | option is given: in the latter case, the pixie connects to it, sends | |
d92b3cee | 183 | a |
184 | .B QUIT | |
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. | |
188 | .\" | |
189 | .SS "Pixie protocol" | |
190 | The protocol used by the pixie is fairly straightforward. | |
191 | .PP | |
192 | Passphrases are known by textual | |
193 | .I tags | |
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. | |
197 | .PP | |
198 | The pixie's responses always have one of the following forms: | |
199 | .TP | |
200 | .BR OK " [\fIphrase\fR]" | |
201 | The request completed successfully. If the request was | |
202 | .B PASS | |
203 | or | |
204 | .BR VERIFY , | |
205 | the response contains the passphrase. | |
206 | .TP | |
207 | .B MISSING | |
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 | |
210 | .B SET | |
211 | request. | |
212 | .TP | |
213 | .BI FAIL " error" | |
214 | The request failed. The | |
215 | .I error | |
216 | is a human-readable explanation of what went wrong. | |
217 | .TP | |
218 | .BI INFO " message" | |
219 | Reports a human-readable informational message. Processing of the | |
220 | request is not complete: further responses will follow. | |
221 | .TP | |
222 | .BI ITEM " tag expires" | |
223 | Reports a passphrase as part of the response to a | |
224 | .B LIST | |
225 | request. One | |
226 | .B ITEM | |
227 | response is given for each passphrase currently known. The | |
228 | .I tag | |
229 | field names the passphrase tag, and the | |
230 | .I expires | |
231 | field gives the number of seconds until the passphrase will expire. | |
232 | Processing of the request is not complete: further responses will | |
233 | follow. | |
234 | .PP | |
235 | The requests available are as follows: | |
236 | .TP | |
237 | .B HELP | |
238 | Returns brief help on the available protocol requests. | |
239 | .TP | |
240 | .B LIST | |
241 | Returns a list of the currently-known passphrases and their expiry | |
242 | information. | |
243 | .TP | |
244 | .BI PASS " tag \fR[\fIexpire\fR]" | |
245 | Returns the passphrase named | |
246 | .IR tag . | |
247 | If the passphrase is unknown, and the pixie fetches it, it should expire | |
248 | after the timeout given by | |
249 | .IR expire , | |
250 | using the same syntax as the | |
251 | .B \-t | |
252 | command-line option. | |
253 | .TP | |
2b511ad9 | 254 | .BI VERIFY " tag \fR[\fIexpire\fR]" |
d92b3cee | 255 | Requests a new passphrase named |
256 | .IR tag . | |
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 | |
259 | the | |
260 | .B PASS | |
261 | request. | |
262 | .TP | |
2b511ad9 | 263 | .BI SET " tag \fR[\fIexpire\fR] " \-\- " phrase" |
d92b3cee | 264 | Sets the value of the passphrase named |
265 | .I tag | |
266 | to be | |
267 | .IR phrase , | |
268 | optionally setting its expiry time to | |
269 | .IR expire . | |
270 | This will usually be a follow-up to a | |
271 | .B MISSING | |
272 | response. If a passphrase with the same tag is already known, it is | |
273 | removed. | |
274 | .TP | |
275 | .BR FLUSH " [\fItag\fR]" | |
276 | If a | |
277 | .I tag | |
278 | is given, flush that passphrase from memory. Otherwise flush | |
279 | .I all | |
280 | passphrases from memory. | |
281 | .TP | |
282 | .B QUIT | |
283 | Asks the pixie to quit. | |
284 | .PP | |
285 | Pixie requests are not case sensitive, in order to make interactive use | |
286 | easier. The responses are guaranteed to be returned in uppercase, | |
287 | however. | |
288 | .\" | |
289 | .SS "Specifying commands" | |
290 | If the pixie is given a | |
291 | .B \-c | |
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: | |
295 | .TP | |
296 | .B %m | |
297 | One of | |
298 | .RB ` Passphrase ', | |
299 | .RB ` "New passphrase" ', | |
300 | or | |
301 | .RB ` "Verify passphrase" ' | |
302 | as appropriate. | |
303 | .TP | |
304 | .B %t | |
305 | The tag of the passphrase being requested. | |
306 | .PP | |
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 | |
310 | ignore its output. | |
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. | |
317 | .SH "OTHER CAVEATS" | |
318 | The pixie's preinitialization checking doesn't do a thorough audit of a | |
2b511ad9 | 319 | directory, in the way that, say, |
d92b3cee | 320 | .BR chkpath (1) |
321 | does. It's your responsibility to make sure that the full path is | |
322 | relatively safe. | |
323 | .PP | |
324 | It's possible, though unlikely, that there's a security hole in the part | |
325 | of the | |
326 | .B pixie | |
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 | |
332 | .B auto-pgp | |
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 | |
335 | noted in the | |
336 | .B auto-pgp | |
337 | documentation. | |
338 | .SH "AUTHOR" | |
f387fcb1 | 339 | Mark Wooding, <mdw@distorted.org.uk> |