9d2e2c65 |
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 |
14 | .SH "SYNOPSIS" |
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 |
24 | .SH "DESCRIPTION" |
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. |
166 | .RB ( SIGQUIT |
167 | was chosen because it can be easily typed at the terminal, usually using |
168 | .BR C-\e .) |
169 | .SH "IMPORTANT SECURITY NOTE" |
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. |
175 | .SH "OTHER CAVEATS" |
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. |
198 | .SH "ACKNOWLEDGEMENTS" |
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, <mdw@nsict.org> |