| 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> |