.B -a authaddr
] [ -s srvname ] [ -m mtpt ] ... attribute ? ...
Factotum serves srv (3) directory #sfactotum , which it binds to /mnt/factotum . It serves the following files: .TF needkey
rpc each open represents a new private channel to factotum
proto when read lists the protocols available
.TP
.B 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 .L ? 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 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 possessing the
same user id as it.
For select protocols such as
.B p9sk1
it can also act as a client for other processes provided
its user id may speak for the other process' user id (see
.IR authsrv (6)).
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: .TF mschap
infauth Inferno's authentication protocol auth (6)
p9any a metaprotocol used to negotiate which actual protocol to use.
p9sk1 a Plan 9 shared key protocol described in
authsrv in section 6 of Plan 9's Programmer's Manual
.TP
.B p9sk2
a variant of
.B p9sk1
described in
.IR authsrv (6)'s
``Remote Execution'' section.
.TP
.B p9cr
a Plan 9 protocol that can use either
.B p9sk1
keys or SecureID tokens.
.TP
.B apop
the challenge/response protocol used by POP3 mail servers.
.TP
.B cram
the challenge/response protocol also used by POP3 mail servers.
.TP
.B chap
the challenge/response protocols used by PPP and PPTP.
.TP
.B mschap
a proprietary Microsoft protocol also used by PPP and PPTP.
.TP
.B rsa
RSA public key decryption, used by SSH and TLS.
pass passwords in the clear.
.TP
.B vnc
.IR vnc (1)'s
challenge/response.
.TP
.B wep
WEP passwords for wireless ethernet cards.
The options are:
.TP
.B -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
.IR cs (8),
the file
.IB net /ndb ,
and finally the network database
.IR ndb (6).
-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
confirming key usage and
entering new keys. It puts its window in the
wm (1) toolbar,
and waits, reading requests from
.B confirm
and
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.
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' section below. Here are some examples:
.EX proto=p9sk1 dom=avayalabs.com user=presotto !password=lucent proto=pass user=tb !password=does.it.matter
The required attributes depend on the authentication protocol. 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, .L 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
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.
Factotum automatically marks
keys with
.B disabled=by.factotum
when they fail during certain authentication
protocols (in particular, the Plan 9 ones).
.PP
Whenever
.I factotum
runs as a server, it must have a
.B p9sk1
key in order to communicate with the authentication
server for validating passwords and challenge/responses of
other users.
1i attr = val The attribute attr must exist in the key and its value must exactly match val
1i attr ? The attribute attr must exist in the key but its value doesn't matter.
1i 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:
1i attr = val This pair must remain unchanged
1i attr ? This attribute needs a value
1i attr The pair must remain unchanged
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 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.
.PP
By default when factotum starts it looks for a
.IR secstore (1)
account on $auth for the user and, if one exists,
prompts for a secstore password in order to fetch
the file
.IR factotum ,
which should contain control file commands.
An example would be
.EX
key dom=x.com proto=p9sk1 user=boyd !hex=26E522ADE2BBB2A229
key proto=rsa service=ssh size=1024 ek=3B !dk=...
.EE
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
.B ssh_genkey
(see
.IR ssh (1)).
.PD
.SS "Confirming key use
.PP
The
.B confirm
file provides a connection from
.I factotum
to a confirmation server, normally the program
.IR auth/fgui .
Whenever a key with the
.B confirm
attribute is used,
.I factotum
requires confirmation of its use. If no process has
.B 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:
.PP
.B confirm
.BI tag= tagno
.I "<key template>
.PP
The reply, written back to
.BR confirm ,
consists of string:
.PP
.BI tag= tagno
.BI answer= xxx
.PP
If
.I xxx
is the string
.B yes
then the use is confirmed and the authentication will proceed.
Otherwise, it fails.
.PP
.B Confirm
is exclusive open and can only be opened by a process with
the same user id as
.IR factotum .
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 missing 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 process with the same user id as factotum .
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 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 structure (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. Otherwise, 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 possible 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 structure.
"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.
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 certificate 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 certificates are represented as strings of the form produced by keyring-certtostr (2); the parameter values are represented 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 hexadecimal 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.
.PP
.B Rsa
requires a key with
.B proto=rsa
in addition to all the hex attributes defining an RSA key:
.BR ek ,
.BR n ,
.BR !p ,
.BR !q ,
.BR !kp ,
.BR !kq ,
.BR !c2 ,
and
.BR !dk .
By convention, programs using the RSA protocol also require a
.B service
attribute set to
.BR ssh ,
.BR sshserve ,
or
.BR tls .
.PP
.B Wep
requires a
.BR key1 ,
.BR key2 ,
or
.BR key3
set to the password to be used.
Starting the protocol causes
.I factotum
to configure the wireless ethernet card
.B #l/ether0
for WEP encryption with the given password.