3 factotum, fgui, userpasswd \- authentication agent
31 is a user-level file system that
32 acts as the authentication agent for a user.
33 It does so by managing a set of
35 A key is a collection of information used to authenticate a particular action.
38 pairs, a key typically contains a user, an authentication domain, a protocol, and
42 presents a two level directory. The first
43 level contains a single directory
45 which in turn contains:
49 each open represents a new private channel to
53 when read lists the protocols available
56 for confiming the use of key
59 allows external programs to control the addition of new keys
65 for maintaining keys; when read, it returns a list of keys.
66 For secret attributes, only the attribute name follow by a
71 In any authentication, the caller typically acts as a client
72 and the callee as a server. The server determines
73 the authentication domain, sometimes after a negotiation with
74 the client. Authentication always requires the client to
75 prove its identity to the server. Under some protocols, the
76 authentication is mutual.
77 Proof is accomplished using secret information kept by factotum
78 in conjunction with a cryptographic protocol.
81 can act in the role of client for any process possessing the
82 same user id as it. For select protocols such as
84 it can also act as a client for other processes provided
85 its user id may speak for the other process' user id (see
88 can act in the role of server for any process.
91 structure is independent of
92 any particular authentication protocol.
94 supports the following protocols:
98 a metaprotocol used to negotiate which actual protocol to use.
101 a Plan 9 shared key protocol described in
103 ``File Service'' section.
110 ``Remote Execution'' section.
113 a Plan 9 protocol that can use either
115 keys or SecureID tokens.
118 the challenge/response protocol used by POP3 mail servers.
121 the challenge/response protocol also used by POP3 mail servers.
124 the challenge/response protocols used by PPP and PPTP.
127 a proprietary Microsoft challenge/response protocol also used by PPP, PPTP and CIFS.
130 version two of Microsofts challenge/response protocol used by WPA.
133 Microsofts NTLMv2 challenge/response protocol used by CIFS.
136 RSA public key decryption, used by SSH and TLS.
139 passwords in the clear.
146 WEP passwords for wireless ethernet cards.
149 WPA passwords for wireless ethernet cards.
155 supplies the address of the authentication server to use.
156 Without this option, it will attempt to find an authentication server by
157 querying the connection server, the file
159 and finally the network database in
163 specifies the mount point to use, by default
167 specifies the service name to use.
170 does not create a service file in
174 turns on 9P tracing, written to standard error.
177 turns on debugging, written to standard error.
180 causes the agent to prompt for the key, write it
184 The agent will prompt for values for any of the
185 attributes ending with a question mark
187 and will append all the supplied
189 pairs. See the section on key templates below.
192 don't look for a secstore.
195 indicates that the agent is running on a
196 CPU server. On starting, it will attempt to get a
202 prompting for anything it needs.
203 It will never subsequently prompt for a
204 key that it doesn't have.
205 This option is typically used by
206 the kernel at boot time.
209 causes the NVRAM to be written.
210 It is only valid with the
213 This option is typically used by
214 the kernel at boot time.
217 causes the agent to prompt for user
220 It is mutually exclusive with
224 This option is typically used by
225 the kernel at boot time.
228 causes the agent not to mark itself `private'
231 so that it can be debugged.
237 is a graphic user interface for confirming key usage and
238 entering new keys. It hides the window in which it starts
239 and waits reading requests from
243 For each requests, it unhides itself and waits for
245 See the sections on key confirmation and key prompting below.
248 queries and prints a cleartext user/password pair from factotum
251 key tuple specified in
253 This can be used by shell scripts to do cleartext password
259 is a space delimited list of
260 .IB attribute = value
261 pairs. An attribute whose name begins with an exclamation point
263 does not appear when reading the
266 The required attributes depend on the authentication protocol.
272 all require a key with
276 attribute identifying the authentication domain, a
278 name valid in that domain, and either a
282 attribute specifying the password or hexadecimal secret
283 to be used. Here is an example:
286 proto=p9sk1 dom=avayalabs.com user=presotto !password=lucent
296 attribute whose value matches the protocol,
306 proto=apop server=mit.edu user=rsc !password=nerdsRus
308 Vnc is similar but does not require a
322 proto=pass user=tb !password=does.it.matter
328 in addition to all the hex attributes defining an RSA key:
338 By convention, programs using the RSA protocol also require a
352 set to the password to be used.
353 Starting the protocol causes
355 to configure the wireless ethernet card
357 for WEP encryption with the given password.
359 All keys can have additional attributes that act either as comments
360 or as selectors to distinguish them in the
364 The factotum owner can use any key stored by factotum.
365 Any key may have one or more
367 attributes listing the users who can use the key
368 as though they were the owner.
369 For example, the TLS and SSH host keys on a server
370 often have an attribute
372 to allow any user (and in particular,
374 to run the TLS or SSH server-side protocol.
378 attribute for restricting how it can be used.
379 If this attribute is missing, the key can be used in any role.
380 The possible values are:
383 for authenticating outbound calls
386 for authenticating inbound calls
389 for authenticating processes whose
390 user id does not match
395 attribute (with any value), the key is not used
396 during any protocols. Factotum automatically marks
398 .B disabled=by.factotum
399 when they fail during certain authentication
400 protocols (in particular, the Plan 9 ones).
405 runs as a server, it must have a
407 key in order to communicate with the authentication
408 server for validating passwords and challenge/responses of
411 Key templates are used by routines that interface to
419 to specify which key and protocol to use for an authentication.
420 Like a key tuple, a key template is also a list of
421 .IB attribute = value
423 It must specify at least the protocol and enough
424 other attributes to uniquely identify a key, or set of keys, to use.
425 The keys chosen are those that match all the attributes specified
426 in the template. The possible attribute/value formats are:
431 must exist in the key and its value must exactly
438 must exist in the key but its value doesn't matter.
443 must exist in the key with a null value
446 Key templates are also used by factotum to request a key either via
447 an RPC error or via the
450 The possible attribute/value formats are:
453 This pair must remain unchanged
456 This attribute needs a value
459 The pair must remain unchanged
461 .SS "Control and Key Management
463 A number of messages can be written to the control file.
466 .B "key \fIattribute-value-list\fP
467 add a new key. This will replace any old key whose
468 public, i.e. non ! attributes, match.
470 .B "delkey \fIattribute-value-list\fP
471 delete a key whose attributes match those given.
474 toggle debugging on and off, i.e., the debugging also
479 By default when factotum starts it looks for a
481 account on $auth for the user and, if one exists,
482 prompts for a secstore password in order to fetch
485 which should contain control file commands.
488 key dom=x.com proto=p9sk1 user=boyd !hex=26E522ADE2BBB2A229
489 key proto=rsa service=ssh size=1024 ek=3B !dk=...
491 where the first line sets a password for
492 challenge/response authentication, strong against dictionary
493 attack by being a long random string, and the second line
494 sets a public/private keypair for ssh authentication,
500 .SS "Confirming key use
504 file provides a connection from
506 to a confirmation server, normally the program
508 Whenever a key with the
512 requires confirmation of its use. If no process has
514 opened, use of the key will be denied.
515 However, if the file is opened a request can be read from it
516 with the following format:
522 The reply, written back to
533 then the use is confirmed and the authentication will proceed.
537 is exclusive open and can only be opened by a process with
540 .SS "Prompting for keys
544 file provides a connection from
546 to a key server, normally the program
550 needs a new key, it first checks to see if
552 is opened. If it isn't, it returns a error to its client.
553 If the file is opened a request can be read from it
554 with the following format:
560 It is up to the reader to then query the user for any missing fields,
561 write the key tuple into the
563 file, and then reply by writing into the
570 is exclusive open and can only be opened by a process with
573 .SS "The RPC Protocol
574 Authentication is performed by
579 setting up the protocol and key to be used (see the
583 shuttling messages back and forth between
585 and the other party (see the
591 if successful, reading back an
596 The RPC protocol is normally embodied by one of the
599 We describe it here should anyone want to extend
602 An RPC consists of writing a request message to
604 followed by reading a reply message back.
605 RPC's are strictly ordered; requests and replies of
606 different RPC's cannot be interleaved.
607 Messages consist of a verb, a single space, and data.
608 The data format depends on the verb. The request verbs are:
610 .B "start \fIattribute-value-list\fP
611 start a new authentication.
612 .I Attribute-value-pair-list
621 and enough other attributes to uniquely identify a key to use.
624 RPC is required before any others. The possible replies are:
630 .B "error \fIstring\fP
640 to send to the other party. The possible replies are:
644 read succeeded, this is zero length message.
647 read succeeded, the data follows the space and is
651 authentication has succeeded, no further RPC's are
655 authentication has succeeded, an
659 can be retrieved with an
663 .B "phase \fIstring\fP
664 its not your turn to read, get some data from
665 the other party and return it with a write RPC.
667 .B "error \fIstring\fP
668 authentication failed,
672 .B "protocol not started
675 RPC needs to precede reads and writes
677 .B "needkey \fIattribute-value-list\fP
678 a key matching the argument is needed. This argument
679 may be passed as an argument to
682 in order to prompt for a key. After that, the
683 authentication may proceed, i.e., the read restarted.
688 send data from the other party to
690 The possible replies are:
696 .B "needkey \fIattribute-value-list\fP
700 the write is too short, get more data from the
701 other party and retry the write.
703 specifies the maximun total number of bytes.
705 .B "phase \fIstring\fP
706 its not your turn to write, get some data from
718 retrieve the AuthInfo structure.
719 The possible replies are:
724 is a marshaled form of the AuthInfo structure.
726 .B "error \fIstring\fP
729 is the reason for the error.
734 retrieve the attributes used in the
737 The possible replies are:
740 .B "ok \fIattribute-value-list\fP
742 .B "error \fIstring\fP
745 is the reason for the error.
749 .B /sys/src/cmd/auth/factotum
projects / plan9front.git / blob