chiark / gitweb /
progs/perftest.c: Use from Glibc syscall numbers.
[catacomb] / progs / pixie.1
CommitLineData
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"
13pixie \- 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"
36The passphrase pixie manages passphrases. When it starts up, it creates
37a Unix-domain socket in a private directory. Clients may connect to it
38and request named passphrases: if the passphrase is known, the pixie
39returns it; otherwise the pixie may (configurably) either return a
40failure code to the client or attempt to prompt the user itself. In the
41former case, the client program will inform the pixie of the selected
42passphrase; in both cases, the passphrase will be remembered for later
43use.
44.PP
45Passphrases which have been stored for a long time without being used
46are removed from memory. On systems which support it, the passphrase
47pixie uses locked memory to prevent sensitive information from being
48swapped out by the operating system.
49.\"
50.SS "Command-line options"
51The
52.B pixie
53program understands the following command-line options:
54.TP
55.B "\-h, \-\-help"
56Prints a relatively comprehensive help message, and exit successfully.
57.TP
58.B "\-V, \-\-version"
59Print the pixie's version number and exit successfully.
60.TP
61.B "\-u, \-\-usage"
62Print a terse usage summary and exit successfully.
63.TP
64.B "\-C, \-\-client"
65Connect to a running pixie as a client. If command-line arguments are
66supplied, they are concatenated with spaces between them and submitted
025c5f4a 67to the pixie as a request; a reply is read from the pixie and formatted:
68information is written to standard output; errors are reported via
69standard error and the exit status. If no command-line arguments are
70given, requestss are read interactively from stdin and sent to the
71pixie; the pixie's responses are printed on stdout uninterpreted.
72.TP
73.B "\-P, \-\-passphrase"
74Connect to a running pixie and request the passphrase with tag
75.IR tag .
76If no pixie is running then request the passphrase from the terminal.
77Print the result on standard output, followed by a newline.
78.TP
79.B "\-PP, \-\-verify-passphrase"
80Connect to a running pixie and request verification of the passphrase
45c0fd36 81with tag
025c5f4a 82.IR tag .
83If no pixie is running, request the passphrase from the terminal. Print
84the result on standard output, followed by a newline.
d92b3cee 85.TP
86.B "\-q, \-\-quiet"
87Causes the pixie to emit fewer log messages.
88.TP
89.B "\-v, \-\-verbose"
90Causes the pixie to emit more verbose log messages.
91.TP
92.BI "\-s, \-\-socket=" socket
93Uses
94.I socket
95as the name of the Unix-domain socket. If running as a client, this is
96the socket to which a connection is made. If running as a server, and
97the socket already exists, the pixie currently listening on the socket
98is told to quit.
99.TP
902cbb33
MW
100.B "\-r, \-\-replace"
101If there's already a pixie listening on the socket then ask it to quit.
102The default behaviour is to report an error and exit in this case.
103.TP
d92b3cee 104.BI "\-c, \-\-command=" command
105Specifies a shell command to be run by the pixie when an unknown
106passphrase is requested by a client.
107.TP
108.BI "\-f, \-\-fetch"
109If an unknown passphrase is requested by a client, the pixie should
110attempt to read a passphrase itself rather than returning an error code.
111.TP
112.BI "\-t, \-\-timeout=" timeout
113Sets a timeout for the user's passphrase. The timeout is, by default,
114in seconds, although a suffix
115.RB ` m ',
116.RB ` h '
117or
118.RB ` d '
119can be added to specify minutes, hours or days respectively. A timeout
120of zero means that the pixie will never time out a passphrase. The
2b511ad9 121default is to time out a passphrase after 15 minutes.
d92b3cee 122.TP
123.B "\-d, \-\-daemon"
124Fork into the background and disassociate from the terminal after
125initializing.
126.TP
127.B "\-l, \-\-syslog"
128Send log messages to the syslog rather than stderr.
129.\"
130.SS "Memory management"
131During initialization, the pixie attempts to allocate a block of memory
5d01b1b9
MW
132from the kernel and protect it against being swapped to disk. On Linux
133and other systems with
134.B RLIMIT_MEMLOCK
135or similar, this should just work assuming that the limit is set
136sensibly. On other systems, this requires that the pixie start with
137root privileges, although it will drop them as soon as it can (before
138parsing command-line options, for example).
d92b3cee 139.PP
140The locked memory is used for all of the passphrases which the pixie
141stores, and for the buffers used to hold requests from clients.
142.\"
143.SS "The pixie socket"
144Communication with the passphrase pixie is performed over a Unix-domain
145socket.
146.PP
147If no socket name is specified on the command line, the pixie reads a
148default from the environment variable
149.BR CATACOMB_PIXIE_SOCKET ;
150if that's not set, a default of
151.RB ` %h/.catacomb/pixie '
152is used.
153.PP
154The socket name may contain substitution directives
155.RB ` %u '
156and
157.RB ` %h ',
158which are replaced by the current user's name and home directory
159respectively.
160.PP
161If
162.B pixie
163is running as a client, it will just attempt to connect to the socket.
164If this fails, it reports an error and exits. The remainder of this
165section deals only with the behaviour of the pixie as a server.
166.PP
167If the socket name has the form
168.IB dir / name
169then the pixie will check that
170.I dir
171is a directory, creating it if it doesn't exist, and that it is not
172readable or writable by anyone other than its owner.
173.PP
174It then attempts to create the socket, giving read and write permissions
175only to its owner. If the attempt succeeds, the pixie's initialization
176is complete.
177.PP
178If the attempt failed because a file with the required name already
179exists and is not a socket, the pixie reports an error and exits. If
902cbb33
MW
180there's already a socket with that name, the pixie quits unless the
181.B \-\-replace
182option is given: in the latter case, the pixie connects to it, sends
d92b3cee 183a
184.B QUIT
185request to the server, waits for a second and retries. If the
186connection attempt fails because there's nobody listening, the pixie
187assumes that the socket is stale, deletes it, and tries again.
188.\"
189.SS "Pixie protocol"
190The protocol used by the pixie is fairly straightforward.
191.PP
192Passphrases are known by textual
193.I tags
194which are assigned by the client. A tag must not contain whitespace
195characters. It's conventional for the tag to be lowercase or mostly
196lowercase, and for multiple words to be joined by dashes.
197.PP
198The pixie's responses always have one of the following forms:
199.TP
200.BR OK " [\fIphrase\fR]"
201The request completed successfully. If the request was
202.B PASS
203or
204.BR VERIFY ,
205the response contains the passphrase.
206.TP
207.B MISSING
208The passphrase requested is not known. The client should request the
209passphrase from the user itself, and then inform the pixie using the
210.B SET
211request.
212.TP
213.BI FAIL " error"
214The request failed. The
215.I error
216is a human-readable explanation of what went wrong.
217.TP
218.BI INFO " message"
219Reports a human-readable informational message. Processing of the
220request is not complete: further responses will follow.
221.TP
222.BI ITEM " tag expires"
223Reports a passphrase as part of the response to a
224.B LIST
225request. One
226.B ITEM
227response is given for each passphrase currently known. The
228.I tag
229field names the passphrase tag, and the
230.I expires
231field gives the number of seconds until the passphrase will expire.
232Processing of the request is not complete: further responses will
233follow.
234.PP
235The requests available are as follows:
236.TP
237.B HELP
238Returns brief help on the available protocol requests.
239.TP
240.B LIST
241Returns a list of the currently-known passphrases and their expiry
242information.
243.TP
244.BI PASS " tag \fR[\fIexpire\fR]"
245Returns the passphrase named
246.IR tag .
247If the passphrase is unknown, and the pixie fetches it, it should expire
248after the timeout given by
249.IR expire ,
250using the same syntax as the
251.B \-t
252command-line option.
253.TP
2b511ad9 254.BI VERIFY " tag \fR[\fIexpire\fR]"
d92b3cee 255Requests a new passphrase named
256.IR tag .
257If the pixie is capable of fetching passphrases, it should ask the user
258for confirmation to guard against typos. Otherwise this is the same as
259the
260.B PASS
261request.
262.TP
2b511ad9 263.BI SET " tag \fR[\fIexpire\fR] " \-\- " phrase"
d92b3cee 264Sets the value of the passphrase named
265.I tag
266to be
267.IR phrase ,
268optionally setting its expiry time to
269.IR expire .
270This will usually be a follow-up to a
271.B MISSING
272response. If a passphrase with the same tag is already known, it is
273removed.
274.TP
275.BR FLUSH " [\fItag\fR]"
276If a
277.I tag
278is given, flush that passphrase from memory. Otherwise flush
279.I all
280passphrases from memory.
281.TP
282.B QUIT
283Asks the pixie to quit.
284.PP
285Pixie requests are not case sensitive, in order to make interactive use
286easier. The responses are guaranteed to be returned in uppercase,
287however.
288.\"
289.SS "Specifying commands"
290If the pixie is given a
291.B \-c
292option, it will use the argument as a shell command in order to request
293passphrases from the user. Before execution, the pixie will perform
294some substitutions on the command string:
295.TP
296.B %m
297One of
298.RB ` Passphrase ',
299.RB ` "New passphrase" ',
300or
301.RB ` "Verify passphrase" '
302as appropriate.
303.TP
304.B %t
305The tag of the passphrase being requested.
306.PP
307The shell command is expected to write the passphrase to its standard
308output, optionally followed by a newline, and exit with status 0. If it
309returns some other exit status, the pixie will assume that it failed and
310ignore its output.
311.SH "IMPORTANT SECURITY NOTE"
312Don't use this software on a machine with a hostile admin. You will
313lose. Any machine with hostile administration must be automatically
314assumed hostile. Never type a passphrase into a hostile machine. Don't
315sent a passphrase over a hostile or potentially hostile network. Don't
316do anything else stupid.
317.SH "OTHER CAVEATS"
318The pixie's preinitialization checking doesn't do a thorough audit of a
2b511ad9 319directory, in the way that, say,
d92b3cee 320.BR chkpath (1)
321does. It's your responsibility to make sure that the full path is
322relatively safe.
323.PP
324It's possible, though unlikely, that there's a security hole in the part
325of the
326.B pixie
327program which can run with setuid privileges. In this case, remove
328setuid privileges immediately \- the program runs quite happily without,
329except that it might not be able to lock pages into memory.
330.SH "ACKNOWLEDGEMENTS"
331The original passphrase pixie was written by Ian Jackson as part of his
332.B auto-pgp
333package. This version of the pixie is major evolution of one I wrote
334for PGP which incorporated the improvements over the original which were
335noted in the
336.B auto-pgp
337documentation.
338.SH "AUTHOR"
f387fcb1 339Mark Wooding, <mdw@distorted.org.uk>