FACTOTUM(4) FACTOTUM(4)
NAME
factotum, feedkey - authentication agent
SYNOPSIS
auth/factotum [ -d ] [ -s srvname ] [ -m mtpt ] ...
attribute? ...
auth/feedkey
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 serves srv(3) directory #sfactotum, which it binds
to /mnt/factotum. It serves the following files:
rpc each open represents a new private channel to
factotum
proto when read lists the protocols available
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,
including the one normally used by Inferno, the authentica-
tion is mutual. Proof is accomplished using secret informa-
tion 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. Factotum can act in the
role of server for any process.
Factotum's structure is independent of any particular
authentication protocol. Factotum currently supports the
following protocols:
infauth Inferno's authentication protocol auth(6)
p9any a metaprotocol used to negotiate which actual
Page 1 Plan 9 (printed 12/30/24)
FACTOTUM(4) FACTOTUM(4)
protocol to use.
p9sk1 a Plan 9 shared key protocol described in authsrv in
section 6 of Plan 9's Programmer's Manual
pass passwords in the clear.
The options are:
-m specifies the mount point to use, by default
/mnt/factotum.
-s specifies the service name to use, by default it is
factotum.
-d turns on debugging, written to standard error.
Feedkey is a wm(1) user interface for entering new keys. It
puts its window in the wm(1) toolbar, and waits, reading
requests from needkey. For each request, it pops open a
window containing suitable prompts and waits for user input.
See the sections on key confirmation and key prompting
below.
Key Tuples
A key tuple is a space-delimited list of attribute=value
pairs. Values containing spaces must be quoted following
the conventions of sh(1). An attribute whose name begins
with an exclamation point (!) is `secret' and does not
appear when reading the ctl file. See the `Protocols' sec-
tion below. Here are some examples:
proto=p9sk1 dom=avayalabs.com user=presotto !password=lucent
proto=pass user=tb !password=does.it.matter
The required attributes depend on the authentication proto-
col. 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
factotum(2) and other 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:
Page 2 Plan 9 (printed 12/30/24)
FACTOTUM(4) FACTOTUM(4)
client
for authenticating outbound calls
server
for authenticating inbound calls
speaksfor
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.
Key Templates
Key templates are used by routines that interface to
factotum, such as those in factotum(2), to specify which key
and protocol to use for an authentication. Like a key
tuple, a key template is also a list of attribute=value
pairs. It must specify at least the protocol 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 attributes match (ie, non ! attributes).
delkey attribute-value-list
Page 3 Plan 9 (printed 12/30/24)
FACTOTUM(4) FACTOTUM(4)
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.
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
factotum(2)).
The RPC protocol is normally embodied by one of the routines
in factotum(2). We describe it here should anyone want to
extend that module.
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
Page 4 Plan 9 (printed 12/30/24)
FACTOTUM(4) FACTOTUM(4)
start a new authentication. Attribute-value-pair-list
must include a proto attribute, a role attribute with
value client or server, and enough other attibutes 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 factotum(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
a key matching the argument is needed. This will
not appear if the needkey file is in use. Other-
wise, a suitable key can be written to ctl and
after that, authentication may proceed (ie, the
read restarted).
write data
send data from the other party to factotum. The possi-
ble replies are:
ok the write succeeded
Page 5 Plan 9 (printed 12/30/24)
FACTOTUM(4) FACTOTUM(4)
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:
ok attribute-value-list
error string
where string is the reason for the error.
Protocols
Factotum can support many authentication protocols, each
implemented by a separate module in the directory
/dis/auth/proto. Currently only a few are implemented in
Inferno:
Infauth is the Inferno public-key authentication protocol
described by auth(6). It requires a key with proto=infauth,
and a !authinfo attribute providing Inferno authentication
data as an S-expression (see sexprs(6)). The S-expression
has five string elements: the signer's public key, the cer-
tificate for the user's public key, the user's secret key,
and the values for parameters alpha and p, selected by the
signer when the key was generated. The keys and certifi-
cates are represented as strings of the form produced by
keyring-certtostr(2); the parameter values are represented
Page 6 Plan 9 (printed 12/30/24)
FACTOTUM(4) FACTOTUM(4)
as binary in the form produced by IPint.iptobytes (see
keyring-ipint(2)). Normally infauth checks that the other
party's key was signed by the signer in the !authinfo data,
but if the key has the attribute anysigner with non-zero
integer value, infauth will accept keys signed by any
signer. The actual signer can be determined by inspecting
the data returned by the authinfo request; the option is
intended for use by services that support calls from many
domains, each with its own signer.
P9sk1 is the shared-secret protocol used to authenticate to
various Plan 9 services. It requires 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 hex-
adecimal secret to be used. P9sk1 normally is invoked by
Plan 9's general authentication protocol, p9any, which is
supported by Inferno's factotum.
Pass requires a key with proto=pass in addition to user and
!password attributes.
SOURCE
/appl/cmd/auth/factotum
SEE ALSO
factotum(2)
Page 7 Plan 9 (printed 12/30/24)