chiark / gitweb /
Initial revision
[pixie] / pixie.1
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"
12 .SH "NAME"
13 pixie \- new, improved PGP passphrase pixie
15 .B pixie
16 .RB [ \-xqv ]
17 .RB [ \-t
18 .IR timeout ]
19 .RB [ \-d
20 .IR dir ]
21 .RI [ socket ]
22 .PP
23 .B pgp-pixie
25 The passphrase pixie sets up a Unix-domain socket and gives your PGP
26 passphrase to anyone who connects to it.  It tries quite hard to make
27 sure that only your own processes are allowed to do this, and to be
28 secure in other ways.  This is mostly useful with Ian Jackson's
29 .B auto-pgp
30 tools.
31 .SS "Command line options"
32 The
33 .B pixie
34 program understands the following command line options:
35 .TP
36 .B "\-h, \-\-help"
37 Prints a relatively comprehensive help message, and exit successfully.
38 .TP
39 .B "\-V, \-\-version"
40 Print the pixie's version number and exit successfully.
41 .TP
42 .B "\-u, \-\-usage"
43 Print a terse usage summary and exit successfully.
44 .TP
45 .B "\-x, \-\-x11"
46 Use the
47 .BR xgetline (1)
48 program to request a passphrase when necessary, rather than requesting
49 the passphrase from the terminal.
50 .RB ( xgetline
51 is part of the
52 .B xtoys
53 distribution.  It requires the GTK library.)  Use the
54 .B +x
55 or
56 .B \-\-no\-x11
57 option to prevent use of
58 .BR xgetline .
59 .TP
60 .B "\-q, \-\-quiet"
61 Produce fewer messages.  This can be used multiple times to make the
62 pixie very quiet.
63 .TP
64 .B "\-v, \-\-verbose"
65 Produce more messages.  This can be used multiple times to make the
66 pixie more verbose.
67 .TP
68 .BI "\-t, \-\-timeout=" timeout
69 Sets a timeout for the user's passphrase.  The timeout is, by default,
70 in seconds, although a suffix
71 .RB ` m ',
72 .RB ` h '
73 or
74 .RB ` d '
75 can be added to specify minutes, hours or days respectively.  A timeout
76 of zero means that the pixie will never time out a passphrase.  The
77 default is to time out a passphrase after 5 minutes.
78 .TP
79 .BI "\-d, \-\-dir=" directory
80 Create, secure and set the named directory as being current before
81 creating a socket.  If the directory does not exist, it is created with
82 mode 700 (readable and writable only by owner); if it does exist, it is
83 checked to ensure that it's owned by the calling user, and it's not
84 readable or writable by anyone other than the caller.
85 .PP
86 If neither of
87 .B \-x
88 nor
89 .B +x
90 are specified on the command line, the pixie decides for itself how to
91 ask for a passphrase.  If standard input is a terminal, it uses the
92 terminal; otherwise it tries
93 .BR xgetline .
94 .PP
95 A socket name is required if no
96 .B \-d
97 option is given; otherwise it's optional and defaults to
98 .BR pass-socket .
99 .PP
100 The
101 .B pgp-pixie
102 shell script provides some default arguments to the main
103 .B pixie
104 program which put the socket in
105 .BR $PGPPATH/.wrapper/pass-socket ,
106 where the other
107 .B auto-pgp
108 tools expect it to be.  It passes any command line options straight on
109 to the main
110 .B pixie
111 program.
112 .SS "Pixie initialization"
113 The pixie initializes itself as follows:
114 .hP 1.
115 If the operating system supports locking pages into memory, the pixie
116 requests a page of memory and then attempts to lock it.  If successful,
117 the passphrase will be stored in this area of memory to prevent its
118 being swapped out to disk.
119 .hP 2.
120 The pixie sets its effective uid the same as its real uid, dropping any
121 setuid privileges the program might have had.
122 .hP 3.
123 If the attempt to lock the page failed, or the operating system doesn't
124 support locking pages, a buffer of normal memory is allocated for the
125 passphrase.
126 .hP 4.
127 The pixie parses its command line options.
128 .hP 5.
129 If a directory was specified with the
130 .B \-d
131 option, the pixie attempts to set it as the current directory.  If the
132 attempt fails because the directory doesn't exist, it is created and the
133 attempt to change directory is made again.  The directory's status is
134 then examined to ensure that it conforms with the security requirements
135 described above.
136 .hP 6.
137 A Unix domain socket is created, with the process's umask (see
138 .BR umask (2))
139 artifically set to 077.  If socket cannot be created, for whatever
140 reason, the pixie reports an error and exits.
141 .hP 7.
142 If the verbosity level is sufficiently high, and a locked memory page
143 could not be allocated, the pixie emits a warning.
144 .SS "Runtime behaviour"
145 After initialization, the pixie enters a loop, waiting for various
146 things to happen.
147 .PP
148 If a client connects to the pixie's socket, the pixie will write its
149 passphrase to the connected socket and then close it.  If the pixie
150 currently has no passphrase, it asks for one and starts a timer (if one
151 was requested by the user).
152 .PP
153 When the passphrase timer expires, all memory of the passphrase is
154 expunged, and the timer is removed.  Any future connections requesting a
155 passphrase will require the user to type one in again.
156 .PP
157 Some signals have a special meaning for the pixie:
158 .TP
159 .BR SIGINT " and " SIGTERM
160 Cause an orderly shutdown of the pixie.  The Unix-domain socket is
161 removed.
162 .TP
163 .BR SIGHUP " and " SIGQUIT
164 Causes the passphrase to be forgotten immediately, as if timed out.
165 This can be handy if you've typed the passphrase wrongly.
167 was chosen because it can be easily typed at the terminal, usually using
168 .BR C-\e .)
170 Don't use this software on a machine with a hostile admin.  You will
171 lose.  Any machine with hostile administration must be automatically
172 assumed hostile.  Never type a passphrase into a hostile machine.  Don't
173 sent a passphrase over a hostile or potentially hostile network.  Don't
174 do anything else stupid.
176 The
177 .B \-d
178 option doesn't do a thorough audit of a directory, in the way that, say
179 .BR chkpath (1)
180 does.  It's your responsibility to make sure that the full path is
181 relatively safe.
182 .PP
183 The
184 .BR xgetline (1)
185 program is not as careful about locking memory as the pixie is.
186 Hopefully the fact that it's a short-lived process means that this isn't
187 a major issue; however, it remains possible that the passphrase typed
188 into
189 .B xgetline
190 could be swapped to disk.
191 .PP
192 It's possible, though unlikely, that there's a security hole in the part
193 of the
194 .B pixie
195 program which can run with setuid privileges.  In this case, remove
196 setuid privileges immediately \- the program runs quite happily without,
197 except that it might not be able to lock pages into memory.
199 The original passphrase pixie was written by Ian Jackson as part of his
200 .B auto-pgp
201 package.  This pixie incorporates some improvements over the original
202 which were noted in the
203 .B auto-pgp
204 documentation.
205 .SH "AUTHOR"
206 Mark Wooding, <>