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