3 factotum \- authentication agent
29 is a user-level file system that
30 acts as the authentication agent for a user.
31 It does so by managing a set of
33 A key is a collection of information used to authenticate a particular action.
36 pairs, a key typically contains a user, an authentication domain, a protocol, and
40 presents the following files:
44 each open represents a new private channel to
48 when read lists the protocols available
51 for confiming the use of key
54 allows external programs to control the addition of new keys
60 for maintaining keys; when read, it returns a list of keys.
61 For secret attributes, only the attribute name follow by a
66 In any authentication, the caller typically acts as a client
67 and the callee as a server. The server determines
68 the authentication domain, sometimes after a negotiation with
69 the client. Authentication always requires the client to
70 prove its identity to the server. Under some protocols, the
71 authentication is mutual.
72 Proof is accomplished using secret information kept by factotum
73 in conjunction with a cryptographic protocol.
76 can act in the role of client for any process possessing the
77 same user id as it. For select protocols such as
79 it can also act as a client for other processes provided
80 its user id may speak for the other process' user id (see
84 can act in the role of server for any process.
87 structure is independent of
88 any particular authentication protocol.
90 supports the following protocols:
94 a metaprotocol used to negotiate which actual protocol to use.
97 a Plan 9 shared key protocol.
104 a Plan 9 protocol that can use either
106 keys or SecureID tokens.
109 the challenge/response protocol used by POP3 mail servers.
112 the challenge/response protocol also used by POP3 mail servers.
115 the challenge/response protocols used by PPP and PPTP.
118 a proprietary Microsoft protocol also used by PPP and PPTP.
121 RSA public key decryption, used by SSH and TLS.
124 passwords in the clear.
131 WEP passwords for wireless ethernet cards.
137 supplies the address of the authentication server to use.
138 Without this option, it will attempt to find an authentication server by
139 querying the connection server, the file
141 and finally the network database in
145 specifies the mount point to use, by default
149 specifies the service name to use.
152 does not create a service file in
156 turns on 9P tracing, written to standard error.
159 turns on debugging, written to standard error.
162 causes the agent to prompt for the key, write it
166 The agent will prompt for values for any of the
167 attributes ending with a question mark
169 and will append all the supplied
171 pairs. See the section on key templates below.
174 don't look for a secstore.
177 indicates that the agent is running on a
178 cpu server. On starting, it will attempt to get a
184 prompting for anything it needs.
185 It will never subsequently prompt for a
186 key that it doesn't have.
187 This option is typically used by
188 the kernel at boot time.
191 causes the NVRAM to be written.
192 It is only valid with the
195 This option is typically used by
196 the kernel at boot time.
199 causes the agent to prompt for user
202 It is mutually exclusive with
206 This option is typically used by
207 the kernel at boot time.
211 .\" is a graphic user interface for confirming key usage and
212 .\" entering new keys. It hides the window in which it starts
213 .\" and waits reading requests from
217 .\" For each requests, it unhides itself and waits for
219 .\" See the sections on key confirmation and key prompting below.
224 is a space delimited list of
225 .IB attribute = value
226 pairs. An attribute whose name begins with an exclamation point
228 does not appear when reading the
231 The required attributes depend on the authentication protocol.
237 all require a key with
241 attribute identifying the authentication domain, a
243 name valid in that domain, and either a
247 attribute specifying the password or hexadecimal secret
248 to be used. Here is an example:
251 proto=p9sk1 dom=avayalabs.com user=presotto !password=lucent
261 attribute whose value matches the protocol,
271 proto=apop server=mit.edu user=rsc !password=nerdsRus
273 Vnc is similar but does not require a
287 proto=pass user=tb !password=does.it.matter
293 in addition to all the hex attributes defining an RSA key:
303 By convention, programs using the RSA protocol also require a
317 set to the password to be used.
318 Starting the protocol causes
320 to configure the wireless ethernet card
322 for WEP encryption with the given password.
324 All keys can have additional attibutes that act either as comments
325 or as selectors to distinguish them in the
329 The factotum owner can use any key stored by factotum.
330 Any key may have one or more
332 attributes listing the users who can use the key
333 as though they were the owner.
334 For example, the TLS and SSH host keys on a server
335 often have an attribute
337 to allow any user (and in particular,
339 to run the TLS or SSH server-side protocol.
343 attribute for restricting how it can be used.
344 If this attribute is missing, the key can be used in any role.
345 The possible values are:
348 for authenticating outbound calls
351 for authenticating inbound calls
354 for authenticating processes whose
355 user id does not match
361 runs as a server, it must have a
363 key in order to communicate with the authentication
364 server for validating passwords and challenge/responses of
367 Key templates are used by routines that interface to
375 to specify which key and protocol to use for an authentication.
376 Like a key tuple, a key template is also a list of
377 .IB attribute = value
379 It must specify at least the protocol and enough
380 other attributes to uniquely identify a key, or set of keys, to use.
381 The keys chosen are those that match all the attributes specified
382 in the template. The possible attribute/value formats are:
387 must exist in the key and its value must exactly
394 must exist in the key but its value doesn't matter.
399 must exist in the key with a null value
402 Key templates are also used by factotum to request a key either via
403 an RPC error or via the
406 The possible attribute/value formats are:
409 This pair must remain unchanged
412 This attribute needs a value
415 The pair must remain unchanged
417 .SS "Control and Key Management
419 A number of messages can be written to the control file.
422 .B "key \fIattribute-value-list\fP
423 add a new key. This will replace any old key whose
424 public, i.e. non ! attributes, match.
426 .B "delkey \fIattribute-value-list\fP
427 delete a key whose attributes match those given.
430 toggle debugging on and off, i.e., the debugging also
435 By default when factotum starts it looks for a
437 account on $auth for the user and, if one exists,
438 prompts for a secstore password in order to fetch
441 which should contain control file commands.
444 key dom=x.com proto=p9sk1 user=boyd !hex=26E522ADE2BBB2A229
445 key proto=rsa service=ssh size=1024 ek=3B !dk=...
447 where the first line sets a password for
448 challenge/response authentication, strong against dictionary
449 attack by being a long random string, and the second line
450 sets a public/private keypair for ssh authentication,
456 .SS "Confirming key use
460 file provides a connection from
462 to a confirmation server, normally the program
464 Whenever a key with the
468 requires confirmation of its use. If no process has
470 opened, use of the key will be denied.
471 However, if the file is opened a request can be read from it
472 with the following format:
478 The reply, written back to
489 then the use is confirmed and the authentication will proceed.
493 is exclusive open and can only be opened by a process with
496 .SS "Prompting for keys
500 file provides a connection from
502 to a key server, normally the program
506 needs a new key, it first checks to see if
508 is opened. If it isn't, it returns a error to its client.
509 If the file is opened a request can be read from it
510 with the following format:
516 It is up to the reader to then query the user for any missing fields,
517 write the key tuple into the
519 file, and then reply by writing into the
526 is exclusive open and can only be opened by a process with
529 .SS "The RPC Protocol
530 Authentication is performed by
535 setting up the protocol and key to be used (see the
539 shuttling messages back and forth between
541 and the other party (see the
547 if successful, reading back an
552 The RPC protocol is normally embodied by one of the
555 We describe it here should anyone want to extend
558 An RPC consists of writing a request message to
560 followed by reading a reply message back.
561 RPC's are strictly ordered; requests and replies of
562 different RPC's cannot be interleaved.
563 Messages consist of a verb, a single space, and data.
564 The data format depends on the verb. The request verbs are:
566 .B "start \fIattribute-value-list\fP
567 start a new authentication.
568 .I Attribute-value-pair-list
577 and enough other attibutes to uniquely identify a key to use.
580 RPC is required before any others. The possible replies are:
586 .B "error \fIstring\fP
596 to send to the other party. The possible replies are:
600 read succeeded, this is zero length message.
603 read succeeded, the data follows the space and is
607 authentication has succeeded, no further RPC's are
611 authentication has succeeded, an
615 can be retrieved with an
619 .B "phase \fIstring\fP
620 its not your turn to read, get some data from
621 the other party and return it with a write RPC.
623 .B "error \fIstring\fP
624 authentication failed,
628 .B "protocol not started
631 RPC needs to precede reads and writes
633 .B "needkey \fIattribute-value-list\fP
634 a key matching the argument is needed. This argument
635 may be passed as an argument to
638 in order to prompt for a key. After that, the
639 authentication may proceed, i.e., the read restarted.
644 send data from the other party to
646 The possible replies are:
652 .B "needkey \fIattribute-value-list\fP
656 the write is too short, get more data from the
657 other party and retry the write.
659 specifies the maximun total number of bytes.
661 .B "phase \fIstring\fP
662 its not your turn to write, get some data from
674 retrieve the AuthInfo structure.
675 The possible replies are:
680 is a marshaled form of the AuthInfo structure.
682 .B "error \fIstring\fP
685 is the reason for the error.
690 retrieve the attributes used in the
693 The possible replies are:
696 .B "ok \fIattribute-value-list\fP
698 .B "error \fIstring\fP
701 is the reason for the error.
705 .B \*9/src/cmd/factotum
