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 | |
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 | |
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 | |
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 | |
5d01b1b9 MW |
128 | from the kernel and protect it against being swapped to disk. On Linux |
129 | and other systems with | |
130 | .B RLIMIT_MEMLOCK | |
131 | or similar, this should just work assuming that the limit is set | |
132 | sensibly. On other systems, this requires that the pixie start with | |
133 | root privileges, although it will drop them as soon as it can (before | |
134 | parsing command-line options, for example). | |
d92b3cee | 135 | .PP |
136 | The locked memory is used for all of the passphrases which the pixie | |
137 | stores, and for the buffers used to hold requests from clients. | |
138 | .\" | |
139 | .SS "The pixie socket" | |
140 | Communication with the passphrase pixie is performed over a Unix-domain | |
141 | socket. | |
142 | .PP | |
143 | If no socket name is specified on the command line, the pixie reads a | |
144 | default from the environment variable | |
145 | .BR CATACOMB_PIXIE_SOCKET ; | |
146 | if that's not set, a default of | |
147 | .RB ` %h/.catacomb/pixie ' | |
148 | is used. | |
149 | .PP | |
150 | The socket name may contain substitution directives | |
151 | .RB ` %u ' | |
152 | and | |
153 | .RB ` %h ', | |
154 | which are replaced by the current user's name and home directory | |
155 | respectively. | |
156 | .PP | |
157 | If | |
158 | .B pixie | |
159 | is running as a client, it will just attempt to connect to the socket. | |
160 | If this fails, it reports an error and exits. The remainder of this | |
161 | section deals only with the behaviour of the pixie as a server. | |
162 | .PP | |
163 | If the socket name has the form | |
164 | .IB dir / name | |
165 | then the pixie will check that | |
166 | .I dir | |
167 | is a directory, creating it if it doesn't exist, and that it is not | |
168 | readable or writable by anyone other than its owner. | |
169 | .PP | |
170 | It then attempts to create the socket, giving read and write permissions | |
171 | only to its owner. If the attempt succeeds, the pixie's initialization | |
172 | is complete. | |
173 | .PP | |
174 | If the attempt failed because a file with the required name already | |
175 | exists and is not a socket, the pixie reports an error and exits. If | |
176 | there's already a socket with that name, the pixie connects to it, sends | |
177 | a | |
178 | .B QUIT | |
179 | request to the server, waits for a second and retries. If the | |
180 | connection attempt fails because there's nobody listening, the pixie | |
181 | assumes that the socket is stale, deletes it, and tries again. | |
182 | .\" | |
183 | .SS "Pixie protocol" | |
184 | The protocol used by the pixie is fairly straightforward. | |
185 | .PP | |
186 | Passphrases are known by textual | |
187 | .I tags | |
188 | which are assigned by the client. A tag must not contain whitespace | |
189 | characters. It's conventional for the tag to be lowercase or mostly | |
190 | lowercase, and for multiple words to be joined by dashes. | |
191 | .PP | |
192 | The pixie's responses always have one of the following forms: | |
193 | .TP | |
194 | .BR OK " [\fIphrase\fR]" | |
195 | The request completed successfully. If the request was | |
196 | .B PASS | |
197 | or | |
198 | .BR VERIFY , | |
199 | the response contains the passphrase. | |
200 | .TP | |
201 | .B MISSING | |
202 | The passphrase requested is not known. The client should request the | |
203 | passphrase from the user itself, and then inform the pixie using the | |
204 | .B SET | |
205 | request. | |
206 | .TP | |
207 | .BI FAIL " error" | |
208 | The request failed. The | |
209 | .I error | |
210 | is a human-readable explanation of what went wrong. | |
211 | .TP | |
212 | .BI INFO " message" | |
213 | Reports a human-readable informational message. Processing of the | |
214 | request is not complete: further responses will follow. | |
215 | .TP | |
216 | .BI ITEM " tag expires" | |
217 | Reports a passphrase as part of the response to a | |
218 | .B LIST | |
219 | request. One | |
220 | .B ITEM | |
221 | response is given for each passphrase currently known. The | |
222 | .I tag | |
223 | field names the passphrase tag, and the | |
224 | .I expires | |
225 | field gives the number of seconds until the passphrase will expire. | |
226 | Processing of the request is not complete: further responses will | |
227 | follow. | |
228 | .PP | |
229 | The requests available are as follows: | |
230 | .TP | |
231 | .B HELP | |
232 | Returns brief help on the available protocol requests. | |
233 | .TP | |
234 | .B LIST | |
235 | Returns a list of the currently-known passphrases and their expiry | |
236 | information. | |
237 | .TP | |
238 | .BI PASS " tag \fR[\fIexpire\fR]" | |
239 | Returns the passphrase named | |
240 | .IR tag . | |
241 | If the passphrase is unknown, and the pixie fetches it, it should expire | |
242 | after the timeout given by | |
243 | .IR expire , | |
244 | using the same syntax as the | |
245 | .B \-t | |
246 | command-line option. | |
247 | .TP | |
2b511ad9 | 248 | .BI VERIFY " tag \fR[\fIexpire\fR]" |
d92b3cee | 249 | Requests a new passphrase named |
250 | .IR tag . | |
251 | If the pixie is capable of fetching passphrases, it should ask the user | |
252 | for confirmation to guard against typos. Otherwise this is the same as | |
253 | the | |
254 | .B PASS | |
255 | request. | |
256 | .TP | |
2b511ad9 | 257 | .BI SET " tag \fR[\fIexpire\fR] " \-\- " phrase" |
d92b3cee | 258 | Sets the value of the passphrase named |
259 | .I tag | |
260 | to be | |
261 | .IR phrase , | |
262 | optionally setting its expiry time to | |
263 | .IR expire . | |
264 | This will usually be a follow-up to a | |
265 | .B MISSING | |
266 | response. If a passphrase with the same tag is already known, it is | |
267 | removed. | |
268 | .TP | |
269 | .BR FLUSH " [\fItag\fR]" | |
270 | If a | |
271 | .I tag | |
272 | is given, flush that passphrase from memory. Otherwise flush | |
273 | .I all | |
274 | passphrases from memory. | |
275 | .TP | |
276 | .B QUIT | |
277 | Asks the pixie to quit. | |
278 | .PP | |
279 | Pixie requests are not case sensitive, in order to make interactive use | |
280 | easier. The responses are guaranteed to be returned in uppercase, | |
281 | however. | |
282 | .\" | |
283 | .SS "Specifying commands" | |
284 | If the pixie is given a | |
285 | .B \-c | |
286 | option, it will use the argument as a shell command in order to request | |
287 | passphrases from the user. Before execution, the pixie will perform | |
288 | some substitutions on the command string: | |
289 | .TP | |
290 | .B %m | |
291 | One of | |
292 | .RB ` Passphrase ', | |
293 | .RB ` "New passphrase" ', | |
294 | or | |
295 | .RB ` "Verify passphrase" ' | |
296 | as appropriate. | |
297 | .TP | |
298 | .B %t | |
299 | The tag of the passphrase being requested. | |
300 | .PP | |
301 | The shell command is expected to write the passphrase to its standard | |
302 | output, optionally followed by a newline, and exit with status 0. If it | |
303 | returns some other exit status, the pixie will assume that it failed and | |
304 | ignore its output. | |
305 | .SH "IMPORTANT SECURITY NOTE" | |
306 | Don't use this software on a machine with a hostile admin. You will | |
307 | lose. Any machine with hostile administration must be automatically | |
308 | assumed hostile. Never type a passphrase into a hostile machine. Don't | |
309 | sent a passphrase over a hostile or potentially hostile network. Don't | |
310 | do anything else stupid. | |
311 | .SH "OTHER CAVEATS" | |
312 | The pixie's preinitialization checking doesn't do a thorough audit of a | |
2b511ad9 | 313 | directory, in the way that, say, |
d92b3cee | 314 | .BR chkpath (1) |
315 | does. It's your responsibility to make sure that the full path is | |
316 | relatively safe. | |
317 | .PP | |
318 | It's possible, though unlikely, that there's a security hole in the part | |
319 | of the | |
320 | .B pixie | |
321 | program which can run with setuid privileges. In this case, remove | |
322 | setuid privileges immediately \- the program runs quite happily without, | |
323 | except that it might not be able to lock pages into memory. | |
324 | .SH "ACKNOWLEDGEMENTS" | |
325 | The original passphrase pixie was written by Ian Jackson as part of his | |
326 | .B auto-pgp | |
327 | package. This version of the pixie is major evolution of one I wrote | |
328 | for PGP which incorporated the improvements over the original which were | |
329 | noted in the | |
330 | .B auto-pgp | |
331 | documentation. | |
332 | .SH "AUTHOR" | |
f387fcb1 | 333 | Mark Wooding, <mdw@distorted.org.uk> |