3 factotum, fgui \- authentication agent
28 is a user-level file system that
29 acts as the authentication agent for a user.
30 It does so by managing a set of
32 A key is a collection of information used to authenticate a particular action.
35 pairs, a key typically contains a user, an authentication domain, a protocol, and
39 presents a two level directory. The first
40 level contains a single directory
42 which in turn contains:
46 each open represents a new private channel to
50 when read lists the protocols available
53 for confiming the use of key
56 allows external programs to control the addition of new keys
62 for maintaining keys; when read, it returns a list of keys.
63 For secret attributes, only the attribute name follow by a
68 In any authentication, the caller typically acts as a client
69 and the callee as a server. The server determines
70 the authentication domain, sometimes after a negotiation with
71 the client. Authentication always requires the client to
72 prove its identity to the server. Under some protocols, the
73 authentication is mutual.
74 Proof is accomplished using secret information kept by factotum
75 in conjunction with a cryptographic protocol.
78 can act in the role of client for any process possessing the
79 same user id as it. For select protocols such as
81 it can also act as a client for other processes provided
82 its user id may speak for the other process' user id (see
85 can act in the role of server for any process.
88 structure is independent of
89 any particular authentication protocol.
91 supports the following protocols:
95 a metaprotocol used to negotiate which actual protocol to use.
98 a Plan 9 shared key protocol described in
100 ``File Service'' section.
107 ``Remote Execution'' section.
110 a Plan 9 protocol that can use either
112 keys or SecureID tokens.
115 the challenge/response protocol used by POP3 mail servers.
118 the challenge/response protocol also used by POP3 mail servers.
121 the challenge/response protocols used by PPP and PPTP.
124 a proprietary Microsoft protocol also used by PPP and PPTP.
127 RSA public key decryption, used by SSH and TLS.
130 passwords in the clear.
137 WEP passwords for wireless ethernet cards.
143 supplies the address of the authentication server to use.
144 Without this option, it will attempt to find an authentication server by
145 querying the connection server, the file
147 and finally the network database in
151 specifies the mount point to use, by default
155 specifies the service name to use.
158 does not create a service file in
162 turns on 9P tracing, written to standard error.
165 turns on debugging, written to standard error.
168 causes the agent to prompt for the key, write it
172 The agent will prompt for values for any of the
173 attributes ending with a question mark
175 and will append all the supplied
177 pairs. See the section on key templates below.
180 don't look for a secstore.
183 indicates that the agent is running on a
184 CPU server. On starting, it will attempt to get a
190 prompting for anything it needs.
191 It will never subsequently prompt for a
192 key that it doesn't have.
193 This option is typically used by
194 the kernel at boot time.
197 causes the NVRAM to be written.
198 It is only valid with the
201 This option is typically used by
202 the kernel at boot time.
205 causes the agent to prompt for user
208 It is mutually exclusive with
212 This option is typically used by
213 the kernel at boot time.
216 causes the agent not to mark itself `private'
219 so that it can be debugged.
225 is a graphic user interface for confirming key usage and
226 entering new keys. It hides the window in which it starts
227 and waits reading requests from
231 For each requests, it unhides itself and waits for
233 See the sections on key confirmation and key prompting below.
238 is a space delimited list of
239 .IB attribute = value
240 pairs. An attribute whose name begins with an exclamation point
242 does not appear when reading the
245 The required attributes depend on the authentication protocol.
251 all require a key with
255 attribute identifying the authentication domain, a
257 name valid in that domain, and either a
261 attribute specifying the password or hexadecimal secret
262 to be used. Here is an example:
265 proto=p9sk1 dom=avayalabs.com user=presotto !password=lucent
275 attribute whose value matches the protocol,
285 proto=apop server=mit.edu user=rsc !password=nerdsRus
287 Vnc is similar but does not require a
301 proto=pass user=tb !password=does.it.matter
307 in addition to all the hex attributes defining an RSA key:
317 By convention, programs using the RSA protocol also require a
331 set to the password to be used.
332 Starting the protocol causes
334 to configure the wireless ethernet card
336 for WEP encryption with the given password.
338 All keys can have additional attributes that act either as comments
339 or as selectors to distinguish them in the
343 The factotum owner can use any key stored by factotum.
344 Any key may have one or more
346 attributes listing the users who can use the key
347 as though they were the owner.
348 For example, the TLS and SSH host keys on a server
349 often have an attribute
351 to allow any user (and in particular,
353 to run the TLS or SSH server-side protocol.
357 attribute for restricting how it can be used.
358 If this attribute is missing, the key can be used in any role.
359 The possible values are:
362 for authenticating outbound calls
365 for authenticating inbound calls
368 for authenticating processes whose
369 user id does not match
374 attribute (with any value), the key is not used
375 during any protocols. Factotum automatically marks
377 .B disabled=by.factotum
378 when they fail during certain authentication
379 protocols (in particular, the Plan 9 ones).
384 runs as a server, it must have a
386 key in order to communicate with the authentication
387 server for validating passwords and challenge/responses of
390 Key templates are used by routines that interface to
398 to specify which key and protocol to use for an authentication.
399 Like a key tuple, a key template is also a list of
400 .IB attribute = value
402 It must specify at least the protocol and enough
403 other attributes to uniquely identify a key, or set of keys, to use.
404 The keys chosen are those that match all the attributes specified
405 in the template. The possible attribute/value formats are:
410 must exist in the key and its value must exactly
417 must exist in the key but its value doesn't matter.
422 must exist in the key with a null value
425 Key templates are also used by factotum to request a key either via
426 an RPC error or via the
429 The possible attribute/value formats are:
432 This pair must remain unchanged
435 This attribute needs a value
438 The pair must remain unchanged
440 .SS "Control and Key Management
442 A number of messages can be written to the control file.
445 .B "key \fIattribute-value-list\fP
446 add a new key. This will replace any old key whose
447 public, i.e. non ! attributes, match.
449 .B "delkey \fIattribute-value-list\fP
450 delete a key whose attributes match those given.
453 toggle debugging on and off, i.e., the debugging also
458 By default when factotum starts it looks for a
460 account on $auth for the user and, if one exists,
461 prompts for a secstore password in order to fetch
464 which should contain control file commands.
467 key dom=x.com proto=p9sk1 user=boyd !hex=26E522ADE2BBB2A229
468 key proto=rsa service=ssh size=1024 ek=3B !dk=...
470 where the first line sets a password for
471 challenge/response authentication, strong against dictionary
472 attack by being a long random string, and the second line
473 sets a public/private keypair for ssh authentication,
479 .SS "Confirming key use
483 file provides a connection from
485 to a confirmation server, normally the program
487 Whenever a key with the
491 requires confirmation of its use. If no process has
493 opened, use of the key will be denied.
494 However, if the file is opened a request can be read from it
495 with the following format:
501 The reply, written back to
512 then the use is confirmed and the authentication will proceed.
516 is exclusive open and can only be opened by a process with
519 .SS "Prompting for keys
523 file provides a connection from
525 to a key server, normally the program
529 needs a new key, it first checks to see if
531 is opened. If it isn't, it returns a error to its client.
532 If the file is opened a request can be read from it
533 with the following format:
539 It is up to the reader to then query the user for any missing fields,
540 write the key tuple into the
542 file, and then reply by writing into the
549 is exclusive open and can only be opened by a process with
552 .SS "The RPC Protocol
553 Authentication is performed by
558 setting up the protocol and key to be used (see the
562 shuttling messages back and forth between
564 and the other party (see the
570 if successful, reading back an
575 The RPC protocol is normally embodied by one of the
578 We describe it here should anyone want to extend
581 An RPC consists of writing a request message to
583 followed by reading a reply message back.
584 RPC's are strictly ordered; requests and replies of
585 different RPC's cannot be interleaved.
586 Messages consist of a verb, a single space, and data.
587 The data format depends on the verb. The request verbs are:
589 .B "start \fIattribute-value-list\fP
590 start a new authentication.
591 .I Attribute-value-pair-list
600 and enough other attributes to uniquely identify a key to use.
603 RPC is required before any others. The possible replies are:
609 .B "error \fIstring\fP
619 to send to the other party. The possible replies are:
623 read succeeded, this is zero length message.
626 read succeeded, the data follows the space and is
630 authentication has succeeded, no further RPC's are
634 authentication has succeeded, an
638 can be retrieved with an
642 .B "phase \fIstring\fP
643 its not your turn to read, get some data from
644 the other party and return it with a write RPC.
646 .B "error \fIstring\fP
647 authentication failed,
651 .B "protocol not started
654 RPC needs to precede reads and writes
656 .B "needkey \fIattribute-value-list\fP
657 a key matching the argument is needed. This argument
658 may be passed as an argument to
661 in order to prompt for a key. After that, the
662 authentication may proceed, i.e., the read restarted.
667 send data from the other party to
669 The possible replies are:
675 .B "needkey \fIattribute-value-list\fP
679 the write is too short, get more data from the
680 other party and retry the write.
682 specifies the maximun total number of bytes.
684 .B "phase \fIstring\fP
685 its not your turn to write, get some data from
697 retrieve the AuthInfo structure.
698 The possible replies are:
703 is a marshaled form of the AuthInfo structure.
705 .B "error \fIstring\fP
708 is the reason for the error.
713 retrieve the attributes used in the
716 The possible replies are:
719 .B "ok \fIattribute-value-list\fP
721 .B "error \fIstring\fP
724 is the reason for the error.
728 .B /sys/src/cmd/auth/factotum