FACTOTUM(4) FACTOTUM(4)
NAME
factotum, fgui - authentication agent
SYNOPSIS
auth/factotum [ -DSdknpu ] [ -a authaddr ] [ -s srvname ] [
-m mtpt ]
auth/factotum -g attribute=value ... attribute? ...
auth/fgui
DESCRIPTION
Factotum is a user-level file system that acts as the
authentication agent for a user. It does so by managing a
set of keys. A key is a collection of information used to
authenticate a particular action. Stored as a list of
attribute=value pairs, a key typically contains a user, an
authentication domain, a protocol, and some secret data.
Factotum presents a two level directory. The first level
contains a single directory factotum, which in turn con-
tains:
rpc each open represents a new private channel to
factotum
proto when read lists the protocols available
confirm for confiming the use of key
needkey allows external programs to control the addition of
new keys
log a log of actions
ctl for maintaining keys; when read, it returns a list
of keys. For secret attributes, only the attribute
name follow by a `?' is returned.
In any authentication, the caller typically acts as a client
and the callee as a server. The server determines the
authentication domain, sometimes after a negotiation with
the client. Authentication always requires the client to
prove its identity to the server. Under some protocols, the
authentication is mutual. Proof is accomplished using
secret information kept by factotum in conjunction with a
cryptographic protocol.
Factotum can act in the role of client for any process pos-
sessing the same user id as it. For select protocols such
as p9sk1 it can also act as a client for other processes
provided its user id may speak for the other process' user
id (see authsrv(6)). Factotum can act in the role of server
for any process.
Page 1 Plan 9 (printed 12/21/24)
FACTOTUM(4) FACTOTUM(4)
Factotum's structure is independent of any particular
authentication protocol. Factotum supports the following
protocols:
p9any a metaprotocol used to negotiate which actual proto-
col to use.
p9sk1 a Plan 9 shared key protocol described in
authsrv(6)'s ``File Service'' section.
p9sk2 a variant of p9sk1 described in authsrv(6)'s
``Remote Execution'' section.
p9cr a Plan 9 protocol that can use either p9sk1 keys or
SecureID tokens.
apop the challenge/response protocol used by POP3 mail
servers.
cram the challenge/response protocol also used by POP3
mail servers.
chap the challenge/response protocols used by PPP and
PPTP.
dsa DSA signatures, used by SSH
mschap a proprietary Microsoft protocol also used by PPP
and PPTP.
rsa RSA encryption and signatures, used by SSH and TLS.
pass passwords in the clear.
vnc vnc(1)'s challenge/response.
wep WEP passwords for wireless ethernet cards. The
``Protocols'' section below describes these proto-
cols in more detail.
The options are:
-a supplies the address of the authentication server to
use. Without this option, it will attempt to find an
authentication server by querying the connection
server, the file <mtpt>/ndb, and finally the network
database in /lib/ndb.
-m specifies the mount point to use, by default /mnt.
-s specifies the service name to use. Without this
option, factotum does not create a service file in
/srv.
-D turns on 9P tracing, written to standard error.
-d turns on debugging, written to standard error.
-g causes the agent to prompt for the key, write it to the
ctl file, and exit. The agent will prompt for values
for any of the attributes ending with a question mark
(?) and will append all the supplied attribute = value
pairs. See the section on key templates below.
Page 2 Plan 9 (printed 12/21/24)
FACTOTUM(4) FACTOTUM(4)
-n don't look for a secstore.
-S indicates that the agent is running on a CPU server.
On starting, it will attempt to get a p9sk1 key from
NVRAM using readnvram (see authsrv(2)), prompting for
anything it needs. It will never subsequently prompt
for a key that it doesn't have. This option is typi-
cally used by the kernel at boot time.
-k causes the NVRAM to be written. It is only valid with
the -S option. This option is typically used by the
kernel at boot time.
-u causes the agent to prompt for user id and writes it to
/dev/hostowner. It is mutually exclusive with -k and
-S. This option is typically used by the kernel at
boot time.
-p causes the agent not to mark itself `private' via
proc(3), so that it can be debugged. It is implied by
-d.
Fgui is a graphic user interface for confirming key usage
and entering new keys. It hides the window in which it
starts and waits reading requests from confirm and needkey.
For each requests, it unhides itself and waits for user
input. See the sections on key confirmation and key prompt-
ing below.
Key Tuples
A key tuple is a whitespace delimited list of
attribute=value pairs. An attribute whose name begins with
an exclamation point (!) does not appear when reading the
ctl file. Values with embedded whitespace or single quotes
are quoted as in rc(1). The required attributes depend on
the authentication protocol.
P9sk1, p9sk2, and p9cr all require a key with proto=p9sk1, a
dom attribute identifying the authentication domain, a user
name valid in that domain, and either a !password or !hex
attribute specifying the password or hexadecimal secret to
be used. Here is an example:
proto=p9sk1 dom=avayalabs.com user=presotto !password=lucent
proto=apop server=mit.edu user=rsc !password=nerdsRus
proto=pass user=tb service=ssh !password=does.it.matter
The ``Protocols'' section below describes the attributes
specific to each supported protocol.
All keys can have additional attributes that act either as
comments or as selectors to distinguish them in the auth(2)
Page 3 Plan 9 (printed 12/21/24)
FACTOTUM(4) FACTOTUM(4)
library calls.
The factotum owner can use any key stored by factotum. Any
key may have one or more owner attributes listing the users
who can use the key as though they were the owner. For
example, the TLS and SSH host keys on a server often have an
attribute owner=* to allow any user (and in particular,
`none') to run the TLS or SSH server-side protocol.
Any key may have a role attribute for restricting how it can
be used. If this attribute is missing, the key can be used
in any role. Common values are:
client
for authenticating outbound calls
server
for authenticating inbound calls
speaksfor
for authenticating processes whose user id does not
match factotum's.
encrypt
for encrypting data
decrypt
for decrypting data
sign for cryptographically signing data
verify
for verifying cryptographic signatures
If a key has a disabled attribute (with any value), the key
is not used during any protocols. Factotum automatically
marks keys with disabled=by.factotum when they fail during
certain authentication protocols (in particular, the Plan 9
ones).
Whenever factotum runs as a server, it must have a p9sk1 key
in order to communicate with the authentication server for
validating passwords and challenge/responses of other users.
Key Templates
Key templates are used by routines that interface to
factotum such as auth_proxy and auth_challenge (see auth(2))
to specify which key and protocol to use for an authentica-
tion. Like a key tuple, a key template is also a list of
attribute=value pairs. It must specify at least the proto-
col and enough other attributes to uniquely identify a key,
or set of keys, to use. The keys chosen are those that
Page 4 Plan 9 (printed 12/21/24)
FACTOTUM(4) FACTOTUM(4)
match all the attributes specified in the template. The
possible attribute/value formats are:
attr=val The attribute attr must exist in the key and its
value must exactly match val
attr? The attribute attr must exist in the key but its
value doesn't matter.
attr The attribute attr must exist in the key with a
null value
Key templates are also used by factotum to request a key
either via an RPC error or via the needkey interface. The
possible attribute/value formats are:
attr=val This pair must remain unchanged
attr? This attribute needs a value
attr The pair must remain unchanged
Control and Key Management
A number of messages can be written to the control file.
The messages are:
key attribute-value-list
add a new key. This will replace any old key whose
public, i.e. non ! attributes, match.
delkey attribute-value-list
delete a key whose attributes match those given.
debug
toggle debugging on and off, i.e., the debugging also
turned on by the -d option.
By default when factotum starts it looks for a secstore(1)
account on $auth for the user and, if one exists, prompts
for a secstore password in order to fetch the file factotum,
which should contain control file commands. An example
would be
key dom=x.com proto=p9sk1 user=boyd !hex=26E522ADE2BBB2A229
key proto=rsa service=ssh size=1024 ek=3B !dk=...
where the first line sets a password for challenge/response
authentication, strong against dictionary attack by being a
long random string, and the second line sets a
public/private keypair for ssh authentication, generated by
ssh_genkey (see ssh(1)).
Confirming key use
The confirm file provides a connection from factotum to a
Page 5 Plan 9 (printed 12/21/24)
FACTOTUM(4) FACTOTUM(4)
confirmation server, normally the program auth/fgui. When-
ever a key with the confirm attribute is used, factotum
requires confirmation of its use. If no process has confirm
opened, use of the key will be denied. However, if the file
is opened a request can be read from it with the following
format:
confirm tag=tagno <key template>
The reply, written back to confirm, consists of string:
tag=tagno answer=xxx
If xxx is the string yes then the use is confirmed and the
authentication will proceed. Otherwise, it fails.
Confirm is exclusive open and can only be opened by a pro-
cess with the same user id as factotum.
Prompting for keys
The needkey file provides a connection from factotum to a
key server, normally the program auth/fgui. Whenever
factotum needs a new key, it first checks to see if needkey
is opened. If it isn't, it returns a error to its client.
If the file is opened a request can be read from it with the
following format:
needkey tag=tagno <key template>
It is up to the reader to then query the user for any miss-
ing fields, write the key tuple into the ctl file, and then
reply by writing into the needkey file the string:
tag=tagno
Needkey is exclusive open and can only be opened by a pro-
cess with the same user id as factotum.
The RPC Protocol
Authentication is performed by
1) opening rpc
2) setting up the protocol and key to be used (see the
start RPC below),
3) shuttling messages back and forth between factotum and
the other party (see the read and write RPC's) until
done
4) if successful, reading back an AuthInfo structure (see
authsrv(2)).
Page 6 Plan 9 (printed 12/21/24)
FACTOTUM(4) FACTOTUM(4)
The RPC protocol is normally embodied by one of the routines
in auth(2). We describe it here should anyone want to extend
the library.
An RPC consists of writing a request message to rpc followed
by reading a reply message back. RPC's are strictly
ordered; requests and replies of different RPC's cannot be
interleaved. Messages consist of a verb, a single space,
and data. The data format depends on the verb. The request
verbs are:
start attribute-value-list
start a new authentication. Attribute-value-pair-list
must include a proto attribute, a role attribute with
value client or server, and enough other attributes to
uniquely identify a key to use. A start RPC is
required before any others. The possible replies
are:
ok start succeeded.
error string
where string is the reason.
read get data from factotum to send to the other party. The
possible replies are:
ok read succeeded, this is zero length message.
ok data
read succeeded, the data follows the space and is
unformatted.
done authentication has succeeded, no further RPC's are
necessary
done haveai
authentication has succeeded, an AuthInfo struc-
ture (see auth(2)) can be retrieved with an
authinfo RPC
phase string
its not your turn to read, get some data from the
other party and return it with a write RPC.
error string
authentication failed, string is the reason.
protocol not started
a start RPC needs to precede reads and writes
needkey attribute-value-list
Page 7 Plan 9 (printed 12/21/24)
FACTOTUM(4) FACTOTUM(4)
a key matching the argument is needed. This argu-
ment may be passed as an argument to factotum -g
in order to prompt for a key. After that, the
authentication may proceed, i.e., the read res-
tarted.
write data
send data from the other party to factotum. The possi-
ble replies are:
ok the write succeeded
needkey attribute-value-list
see above
toosmall n
the write is too short, get more data from the
other party and retry the write. n specifies the
maximun total number of bytes.
phase string
its not your turn to write, get some data from
factotum first.
done see above
done haveai
see above
readhex, writehex
like read and write, except that an ok response to
readhex returns the data encoded as a long hexadecimal
string, and the argument to writehex is expected to be
a long hexadecimal string. These are useful for manu-
ally debugging of binary protocols.
authinfo
retrieve the AuthInfo structure. The possible replies
are:
ok data
data is a marshaled form of the AuthInfo struc-
ture.
error string
where string is the reason for the error.
attr retrieve the attributes used in the start RPC. The
possible replies are:
ok attribute-value-list
Page 8 Plan 9 (printed 12/21/24)
FACTOTUM(4) FACTOTUM(4)
error string
where string is the reason for the error.
Protocols
Factotum supports many authentication types, each with its
own roles and required key attributes.
P9any, p9sk1, p9sk2, and p9cr are used to authenticate to
Plan 9 systems; valid roles are client and server. All
require proto=p9sk1 keys with user, dom (authentication
domain), and !password attributes.
P9sk1 and p9sk2 are the Plan 9 shared-key authentication
protocols. P9sk2 is a deprecated form of p9sk1 that
neglects to authenticate the server.
P9any is a meta-protocol that negotiates a protocol (p9sk1
or p9sk2) and an authentication domain and then invokes the
given protocol with a dom= attribute.
P9any, p9sk1, and p9sk2 are intended to be proxied via
auth_proxy (see auth(2)).
P9cr is a textual challenge-response protocol; roles are
client and server. It uses p9sk1 keys as described above.
The protocol with factotum is textual: client writes a user
name, server responds with a challenge, client writes a
response, server responds with ok or bad. Typically this
information is wrapped in other protocols before being sent
over the network.
Vnc is the challenge-response protocol used by vnc(1); valid
roles are client and server. The client protocol requires a
proto=vnc key with attribute !password. Conventionally,
client keys also have user and server attributes. The
server protocol requires a p9sk1 key as described above.
The protocol with factotum is the same as p9cr, except that
the challenge and response are not textual.
Apop and cram are challenge-response protocols typically
used to authenticate to mail servers. The client protocols
require proto=apop or proto=cram keys with user and
!password attributes. Conventionally, client keys also have
server attributes. The server protocol requires a p9sk1 key
as described above. The protocol with factotum is textual:
server writes a challenge of the form random@domain, client
responds with user name and then a hexadecimal response (two
separate writes), and then the server responds with ok or
bad.
Chap and mschap are challenge-response protocols used in PPP
sessions; valid roles are client and server. The client
Page 9 Plan 9 (printed 12/21/24)
FACTOTUM(4) FACTOTUM(4)
protocols require proto=chap or proto=mschap keys with user
and !password attributes. Conventionally, client keys also
have server attributes. The server protocol requires a
p9sk1 key as described above. The protocol with factotum
is: server writes an 8-byte binary challenge, client
responds with user name and then a Chapreply or MSchapreply
structure (defined in <auth.h> ).
Pass is a client-only protocol that hands out passwords from
proto=pass keys with user and !password attributes. The
protocol is a single read that returns a string: a space-
separated quoted user name and password that can be parsed
with tokenize (see getfields(2)). Conventionally, client
keys have distinguishing attributes like service and server
that can be specified in the start message to select a key.
Wep is a client-only pseudo-protocol that initializes the
encryption key on a wireless ethernet device. It uses
proto=wep keys with !key1, !key2, or !key3 attributes. The
protocol with factotum is: the client writes a device name
that must begin with `#l'. In response, factotum opens the
device's control file, sets the wireless secret using the
key, and turns on encryption. If the key has an essid
attribute, factotum uses it to set the wireless station ID.
Rsa is an implementation of the RSA protocol. Valid roles
are decrypt, encrypt, sign, and verify. Rsa uses proto=rsa
keys with ek and n attributes, large integers specifying the
public half of the key. If a key is to be used for decryp-
tion or signing, then it must also have attributes !p, !q,
!kp, !kq, !c2, and !dk specifying the private half of the
key; see rsa(2). Conventionally, rsa keys also have service
attributes specifying the context in which the key is used:
ssh (SSH version 1), ssh-rsa (SSH version 2), or tls (SSL
and TLS). If an SSH key has a comment attribute, that com-
ment is presented to remote SSH servers during key negotia-
tion. The protocol for encryption (decryption) is: write
the message, then read back the encrypted (decrypted) form.
The protocol for signing is: write a hash of the actual mes-
sage, then read back the signature. The protocol for veri-
fying a signature is: write the message hash, write the pur-
ported signature, then read back ok or bad telling whether
the signature could be verified. The hash defaults to SHA1
but can be specified by a hash attribute on the key. Valid
hash functions are md5 and sha1. The hash function must be
known to factotum because the signature encodes the type of
hash used. The encrypt and verify operations are included
as a convenience; factotum is not using any private informa-
tion to perform them.
Dsa is an implementation of the NIST digital signature algo-
rithm. Valid roles are sign and verify. It uses proto=dsa
Page 10 Plan 9 (printed 12/21/24)
FACTOTUM(4) FACTOTUM(4)
keys with p, q, alpha, and key attributes. If the key is to
be used for signing, it must also have a !secret attribute;
see dsa(2). Conventionally, dsa keys also have service
attributes specifying the context in which the key is used:
ssh-dss (SSH version 2) is the only one. If an SSH key has
a comment attribute, that comment is presented to SSH
servers during key negotiation. The protocol for signing
and verifying is the same as the RSA protocol. Unlike rsa,
the dsa protocol ignores the hash attribute; it always uses
SHA1.
Httpdigest is a client-only MD5-based challenge-response
protocol used in HTTP; see RFC 2617. It uses
proto=httpdigest keys with user, realm, and !password
attributes. The protocol with factotum is textual: write
the challenge, read the response. The challenge is a string
with three space-separated fields nonce, method, and uri,
parseable with tokenize. The response is a hexadecimal
string of length 32.
SEE ALSO
secstore(1).
SOURCE
/sys/src/cmd/auth/factotum
Page 11 Plan 9 (printed 12/21/24)