FACTOTUM(4) FACTOTUM(4)
NAME
factotum, fgui, userpasswd - authentication agent
SYNOPSIS
auth/factotum [ -DdknpuS ] [ -a asaddr ] [ -s srvname ] [ -m
mtpt ]
auth/factotum -g attribute=value ... attribute? ...
auth/fgui
auth/userpasswd fmt
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 and dp9ik it can also act as a client for other
processes provided its user id may speak for the other pro-
cess' user id (see authsrv(6)). Factotum can act in the role
Page 1 Plan 9 (printed 12/27/24)
FACTOTUM(4) FACTOTUM(4)
of server for any process.
Factotum's structure is independent of any particular
authentication protocol. Factotum supports the following
protocols:
p9any a metaprotocol used to negotiate which actual pro-
tocol to use.
p9sk1 legacy Plan 9 shared key protocol described in
authsrv(6)'s ``Ticket Service'' and ``P9sk1'' sec-
tions.
dp9ik extended version of p9sk1 that adds password
bruteforce resistance and forward secrecy (see
authsrv(6)'s ``Password authenticated key
exchange'' and ``Dp9ik'' sections).
p9cr legacy 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.
mschap a proprietary Microsoft challenge/response proto-
col also used by PPP, PPTP and CIFS.
mschapv2 version two of Microsofts challenge/response pro-
tocol used by WPA.
mschap2 Microsofts NTLMv2 challenge/response protocol used
by CIFS.
rsa RSA public key decryption, used by SSH and TLS.
pass passwords in the clear.
vnc vnc(1)'s challenge/response.
wpapsk WPA passwords for wireless ethernet cards.
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.
Page 2 Plan 9 (printed 12/27/24)
FACTOTUM(4) FACTOTUM(4)
-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.
-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 p9sk1 and dp9ik
keys from NVRAM using readnvram (see authsrv(2)),
prompting for anything it needs. It will never subse-
quently prompt for a key that it doesn't have. This
option is typically 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.
Userpasswd queries and prints a cleartext user/password pair
from factotum for the proto=pass key tuple specified in fmt.
This can be used by shell scripts to do cleartext password
authentication.
Key Tuples
A key tuple is a space delimited list of attribute=value
pairs. An attribute whose name begins with an exclamation
point (!) does not appear when reading the ctl file. The
required attributes depend on the authentication protocol.
Dp9ik, p9sk1 and p9cr all require a key with proto=dp9ik or
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 hex-
adecimal secret to be used. Here is an example:
Page 3 Plan 9 (printed 12/27/24)
FACTOTUM(4) FACTOTUM(4)
proto=dp9ik dom=9front user=glenda !password=secret
Apop, cram, chap, and mschap, require a key with a proto
attribute whose value matches the protocol, in addition to
server, user, and !password attributes; e.g.
proto=apop server=mit.edu user=rsc !password=nerdsRus
Vnc is similar but does not require a user attribute.
Pass requires a key with proto=pass in addition to user and
!password attributes; e.g.
proto=pass user=tb !password=does.it.matter
Rsa requires a key with proto=rsa in addition to all the hex
attributes defining an RSA key: ek, n, !p, !q, !kp, !kq,
!c2, and !dk. By convention, programs using the RSA proto-
col also require a service attribute set to ssh or tls.
All keys can have additional attributes that act either as
comments or as selectors to distinguish them in the auth(2)
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. The possible values are:
client
for authenticating outbound calls
server
for authenticating inbound calls
speakfor
for authenticating processes whose user id does not
match factotum's.
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 dp9ik or
p9sk1 keys in order to communicate with the authentication
Page 4 Plan 9 (printed 12/27/24)
FACTOTUM(4) FACTOTUM(4)
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
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
Page 5 Plan 9 (printed 12/27/24)
FACTOTUM(4) FACTOTUM(4)
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.
Confirming key use
The confirm file provides a connection from factotum to a
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
Page 6 Plan 9 (printed 12/27/24)
FACTOTUM(4) FACTOTUM(4)
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)).
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
Page 7 Plan 9 (printed 12/27/24)
FACTOTUM(4) FACTOTUM(4)
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
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
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:
Page 8 Plan 9 (printed 12/27/24)
FACTOTUM(4) FACTOTUM(4)
ok attribute-value-list
error string
where string is the reason for the error.
SOURCE
/sys/src/cmd/auth/factotum
SEE ALSO
authsrv(6)
Page 9 Plan 9 (printed 12/27/24)