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 DSA signatures, used by SSH
121 a proprietary Microsoft protocol also used by PPP and PPTP.
124 RSA encryption and signatures, used by SSH and TLS.
127 passwords in the clear.
134 WEP passwords for wireless ethernet cards.
136 The ``Protocols'' section below describes these protocols in more detail.
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.
217 .\" is a graphic user interface for confirming key usage and
218 .\" entering new keys. It hides the window in which it starts
219 .\" and waits reading requests from
223 .\" For each requests, it unhides itself and waits for
225 .\" See the sections on key confirmation and key prompting below.
230 is a space delimited list of
231 .IB attribute = value
232 pairs. An attribute whose name begins with an exclamation point
234 does not appear when reading the
237 Here are some examples:
239 proto=p9sk1 dom=avayalabs.com user=presotto !password=lucent
240 proto=apop server=mit.edu user=rsc !password=nerdsRus
241 proto=pass user=tb service=ssh !password=does.it.matter
243 The ``Protocols'' section below describes the attributes
244 specific to each supported protocol.
246 All keys can have additional attibutes that act either as comments
247 or as selectors to distinguish them in the
251 The factotum owner can use any key stored by factotum.
252 Any key may have one or more
254 attributes listing the users who can use the key
255 as though they were the owner.
256 For example, the TLS and SSH host keys on a server
257 often have an attribute
259 to allow any user (and in particular,
261 to run the TLS or SSH server-side protocol.
265 attribute for restricting how it can be used.
266 If this attribute is missing, the key can be used in any role.
270 for authenticating outbound calls
273 for authenticating inbound calls
276 for authenticating processes whose
277 user id does not match
287 for cryptographically signing data
290 for verifying cryptographic signatures
295 runs as a server, it must have a
297 key in order to communicate with the authentication
298 server for validating passwords and challenge/responses of
301 Key templates are used by routines that interface to
309 to specify which key and protocol to use for an authentication.
310 Like a key tuple, a key template is also a list of
311 .IB attribute = value
313 It must specify at least the protocol and enough
314 other attributes to uniquely identify a key, or set of keys, to use.
315 The keys chosen are those that match all the attributes specified
316 in the template. The possible attribute/value formats are:
321 must exist in the key and its value must exactly
328 must exist in the key but its value doesn't matter.
333 must exist in the key with a null value
336 Key templates are also used by factotum to request a key either via
337 an RPC error or via the
340 The possible attribute/value formats are:
343 This pair must remain unchanged
346 This attribute needs a value
349 The pair must remain unchanged
351 .SS "Control and Key Management
353 A number of messages can be written to the control file.
356 .B "key \fIattribute-value-list\fP
357 add a new key. This will replace any old key whose
358 public, i.e. non ! attributes, match.
360 .B "delkey \fIattribute-value-list\fP
361 delete a key whose attributes match those given.
364 toggle debugging on and off, i.e., the debugging also
369 By default when factotum starts it looks for a
371 account on $auth for the user and, if one exists,
372 prompts for a secstore password in order to fetch
375 which should contain control file commands.
378 key dom=x.com proto=p9sk1 user=boyd !hex=26E522ADE2BBB2A229
379 key proto=rsa service=ssh size=1024 ek=3B !dk=...
381 where the first line sets a password for
382 challenge/response authentication, strong against dictionary
383 attack by being a long random string, and the second line
384 sets a public/private keypair for ssh authentication,
390 .SS "Confirming key use
394 file provides a connection from
396 to a confirmation server, normally the program
398 Whenever a key with the
402 requires confirmation of its use. If no process has
404 opened, use of the key will be denied.
405 However, if the file is opened a request can be read from it
406 with the following format:
412 The reply, written back to
423 then the use is confirmed and the authentication will proceed.
427 is exclusive open and can only be opened by a process with
430 .SS "Prompting for keys
434 file provides a connection from
436 to a key server, normally the program
440 needs a new key, it first checks to see if
442 is opened. If it isn't, it returns a error to its client.
443 If the file is opened a request can be read from it
444 with the following format:
450 It is up to the reader to then query the user for any missing fields,
451 write the key tuple into the
453 file, and then reply by writing into the
460 is exclusive open and can only be opened by a process with
463 .SS "The RPC Protocol
464 Authentication is performed by
469 setting up the protocol and key to be used (see the
473 shuttling messages back and forth between
475 and the other party (see the
481 if successful, reading back an
486 The RPC protocol is normally embodied by one of the
489 We describe it here should anyone want to extend
492 An RPC consists of writing a request message to
494 followed by reading a reply message back.
495 RPC's are strictly ordered; requests and replies of
496 different RPC's cannot be interleaved.
497 Messages consist of a verb, a single space, and data.
498 The data format depends on the verb. The request verbs are:
500 .B "start \fIattribute-value-list\fP
501 start a new authentication.
502 .I Attribute-value-pair-list
511 and enough other attibutes to uniquely identify a key to use.
514 RPC is required before any others. The possible replies are:
520 .B "error \fIstring\fP
530 to send to the other party. The possible replies are:
534 read succeeded, this is zero length message.
537 read succeeded, the data follows the space and is
541 authentication has succeeded, no further RPC's are
545 authentication has succeeded, an
549 can be retrieved with an
553 .B "phase \fIstring\fP
554 its not your turn to read, get some data from
555 the other party and return it with a write RPC.
557 .B "error \fIstring\fP
558 authentication failed,
562 .B "protocol not started
565 RPC needs to precede reads and writes
567 .B "needkey \fIattribute-value-list\fP
568 a key matching the argument is needed. This argument
569 may be passed as an argument to
572 in order to prompt for a key. After that, the
573 authentication may proceed, i.e., the read restarted.
578 send data from the other party to
580 The possible replies are:
586 .B "needkey \fIattribute-value-list\fP
590 the write is too short, get more data from the
591 other party and retry the write.
593 specifies the maximun total number of bytes.
595 .B "phase \fIstring\fP
596 its not your turn to write, get some data from
607 .B readhex\fR, \fPwritehex
616 returns the data encoded as
617 a long hexadecimal string,
620 is expected to be a long hexadecimal string.
621 These are useful for manually debugging of binary protocols.
624 retrieve the AuthInfo structure.
625 The possible replies are:
630 is a marshaled form of the AuthInfo structure.
632 .B "error \fIstring\fP
635 is the reason for the error.
640 retrieve the attributes used in the
643 The possible replies are:
646 .B "ok \fIattribute-value-list\fP
648 .B "error \fIstring\fP
651 is the reason for the error.
655 Factotum supports many authentication types, each
656 with its own roles and required key attributes.
663 are used to authenticate to Plan 9 systems;
675 (authentication domain),
683 are the Plan 9 shared-key authentication protocols.
685 is a deprecated form of
687 that neglects to authenticate the server.
690 is a meta-protocol that negotiates a protocol
694 and an authentication domain and then invokes the
695 given protocol with a
703 are intended to be proxied via
707 .\" The protocols follow
711 .\" XXX - write about how server keys are selected and used
712 .\" XXX - write about protocol itself
713 .\" XXX - write about server ai
716 is a textual challenge-response protocol;
723 keys as described above.
727 client writes a user name,
728 server responds with a challenge,
729 client writes a response,
734 Typically this information is wrapped in other protocols
735 before being sent over the network.
738 is the challenge-response protocol used by
744 The client protocol requires a
748 Conventionally, client keys also have
753 The server protocol requires a
755 key as described above.
760 except that the challenge and response are not textual.
765 are challenge-response protocols typically
768 The client protocols require
777 Conventionally, client keys also have
780 The server protocol requires a
782 key as described above.
786 server writes a challenge of the form
787 .IB random @ domain \fR,
788 client responds with user name
789 and then a hexadecimal response
790 (two separate writes),
791 and then the server responds with
799 are challenge-response protocols used in PPP sessions;
804 The client protocols require
813 Conventionally, client keys also have
816 The server protocol requires a
818 key as described above.
819 The protocol with factotum is:
820 server writes an 8-byte binary challenge,
821 client responds with user name
826 structure (defined in
830 is a client-only protocol that hands out passwords
838 The protocol is a single read that returns
839 a string: a space-separated quoted user name and password
840 that can be parsed with
844 Conventionally, client keys have distinguishing attributes
849 that can be specified in the
851 message to select a key.
854 is a client-only pseudo-protocol that initializes the encryption
855 key on a wireless ethernet device.
867 the client writes a device name
872 opens the device's control file, sets the wireless secret using the key,
873 and turns on encryption.
878 uses it to set the wireless station ID.
881 is an implementation of the RSA protocol.
895 attributes, large integers specifying the public half
897 If a key is to be used for decryption or signing,
898 then it must also have attributes
906 specifying the private half of the key;
913 attributes specifying the context in which the key is used:
923 attribute, that comment is presented to remote SSH servers
924 during key negotiation.
926 encryption (decryption) is:
927 write the message, then read back the encrypted (decrypted) form.
928 The protocol for signing is:
929 write a hash of the actual message,
930 then read back the signature.
931 The protocol for verifying a signature is:
932 write the message hash,
933 write the purported signature,
938 telling whether the signature could be verified.
939 The hash defaults to SHA1 but can be specified by a
941 attribute on the key.
942 Valid hash functions are
946 The hash function must be known to
948 because the signature encodes the type of hash used.
953 operations are included as a convenience;
955 is not using any private information to perform them.
958 is an implementation of the NIST digital signature algorithm.
972 If the key is to be used for signing, it must also have a
981 attributes specifying the context in which the key is used:
987 attribute, that comment is presented to SSH servers during
989 The protocol for signing and verifying
990 is the same as the RSA protocol.
997 attribute; it always uses SHA1.
1000 is a client-only MD5-based challenge-response protocol used in HTTP; see RFC 2617.
1009 The protocol with factotum is textual:
1010 write the challenge, read the response.
1011 The challenge is a string with three space-separated fields
1018 The response is a hexadecimal string of length 32.
1020 .B \*9/src/cmd/auth/factotum
