path: root/man/4/factotum

.TH FACTOTUM 4
.SH NAME
factotum, feedkey \- authentication agent
.SH SYNOPSIS
.B auth/factotum
[
.B -d
.\" ] [
.\" .B -a authaddr
] [
.B -s
.I srvname
] [
.B -m
.I mtpt
]
.B ...
.IB attribute ?
.B ...
.PP
.B auth/feedkey
.SH DESCRIPTION
.I Factotum
is a user-level file system that
acts as the authentication agent for a user.
It does so by managing a set of
.IR keys .
A key is a collection of information used to authenticate a particular action.
Stored as a list of
.IB attribute = value
pairs, a key typically contains a user, an authentication domain, a protocol, and
some secret data.
.PP
.I Factotum
serves
.IR srv (3)
directory
.BR #sfactotum ,
which it binds to
.BR /mnt/factotum .
It serves the following files:
.TF needkey
.TP
.B rpc
each open represents a new private channel to
.I factotum
.TP
.B proto
when read lists the protocols available
.\" .TP
.\" .B confirm
.\" for confiming the use of key
.TP
.B needkey
allows external programs to control the addition of new keys
.TP
.B log
a log of actions
.TP
.B 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.
.PD
.PP
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
.I factotum
in conjunction with a cryptographic protocol.
.PP
.I 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)).
.I Factotum
can act in the role of server for any process.
.PP
.IR Factotum 's
structure is independent of
any particular authentication protocol.
.I Factotum
currently supports the following protocols:
.TF mschap
.TP
.B infauth
Inferno's authentication protocol
.IR auth (6)
.TP
.B p9any
a metaprotocol used to negotiate which actual protocol to use.
.TP
.B p9sk1
a Plan 9 shared key protocol described in
.I 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.
.TP
.B pass
passwords in the clear.
.\" .TP
.\" .B vnc
.\" .IR vnc (1)'s
.\" challenge/response.
.\" .TP
.\" .B wep
.\" WEP passwords for wireless ethernet cards.
.PD
.PP
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).
.TP
.B \-m
specifies the mount point to use, by default
.BR /mnt/factotum .
.TP
.B \-s
specifies the service name to use,
by default it is
.BR factotum .
.TP
.B \-d
turns on debugging, written to standard error.
.PD
.PP
.I Feedkey
is a
.IR wm (1)
user interface for
.\" confirming key usage and
entering new keys.  It puts its window in the
.IR wm (1)
toolbar,
and waits, reading requests from
.\" .B confirm
.\" and
.BR 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.
.SS "Key Tuples
.PP
A
.I "key tuple
is a space-delimited list of 
.IB attribute = value
pairs.  Values containing spaces must be quoted following
the conventions of
.IR sh (1).
An attribute whose name begins with an exclamation point
.RB ( ! )
is `secret' and
does not appear when reading the
.B ctl
file.
See the `Protocols' section below.
Here are some examples:
.PP
.EX
    proto=p9sk1 dom=avayalabs.com user=presotto !password=lucent
    proto=pass user=tb !password=does.it.matter
.EE
.PP
The required attributes depend on the authentication protocol.
The `Protocols' section below describes the attributes specific
to each supported protocol.
.PP
All keys can have additional attributes that act either as comments
or as selectors to distinguish them in the
.IR factotum (2)
and other
library calls.
.PP
The factotum owner can use any key stored by factotum.
Any key may have one or more
.B 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
.B owner=*
to allow any user (and in particular,
.L none )
to run the TLS or SSH server-side protocol.
.PP
Any key may have a
.B 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:
.TP
.B client
for authenticating outbound calls
.TP
.B server
for authenticating inbound calls
.TP
.B speaksfor
for authenticating processes whose
user id does not match
.IR factotum 's.
.PP
If a key has a
.B 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).
.PD
.\" .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.
.SS "Key Templates
Key templates are used by routines that interface to
.IR factotum ,
such as those in
.IR 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 
.IB 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:
.TP 1i
.IB attr = val
The attribute
.I attr
must exist in the key and its value must exactly
match
.I val
.TP 1i
.IB attr ?
The attribute
.I attr
must exist in the key but its value doesn't matter.
.TP 1i
.I attr
The attribute
.I attr
must exist in the key with a null value
.PD
.PP
Key templates are also used by
.I factotum
to request a key either via
an RPC error or via the
.B needkey
interface.
The possible attribute/value formats are:
.TP 1i
.IB attr = val
This pair must remain unchanged
.TP 1i
.IB attr ?
This attribute needs a value
.TP 1i
.I attr
The pair must remain unchanged
.PD
.SS "Control and Key Management
.PP
A number of messages can be written to the control file.
The messages are:
.TP
.B "key \fIattribute-value-list\fP
add a new key.  This will replace any old key whose
public attributes match (ie, non
.B !
attributes).
.TP
.B "delkey \fIattribute-value-list\fP
delete a key whose attributes match those given.
.TP
.B debug
toggle debugging on and off, i.e., the debugging also
turned on by the
.B \-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 .
.SS "Prompting for keys
.PP
The 
.B needkey
file provides a connection from
.I factotum
to a key server, normally the program
.IR auth/fgui .
Whenever
.I factotum
needs a new key, it first checks to see if
.B 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:
.PP
.B needkey
.BI tag= tagno
.I "<key template>
.PP
It is up to the reader to then query the user for any missing fields,
write the key tuple into the
.B ctl
file, and then reply by writing into the
.B needkey
file the string:
.PP
.BI tag= tagno
.PP
.B Needkey
is exclusive open and can only be opened by a process with
the same user id as
.IR factotum .
.SS "The RPC Protocol
Authentication is performed by
.IP 1)
opening
.BR rpc
.IP 2)
setting up the protocol and key to be used (see the
.B start
RPC below),
.IP 3)
shuttling messages back and forth between
.IR factotum
and the other party (see the
.B read
and
.B write
RPC's) until done
.IP 4)
if successful, reading back an
.I AuthInfo
structure (see
.IR factotum (2)).
.PP
The RPC protocol is normally embodied by one of the
routines in
.IR factotum (2).
We describe it here should anyone want to extend
that module.
.PP
An RPC consists of writing a request message to
.B 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:
.TP
.B "start \fIattribute-value-list\fP
start a new authentication.
.I Attribute-value-pair-list
must include a
.B proto
attribute, a
.B role
attribute with value
.B client
or
.BR server ,
and enough other attibutes to uniquely identify a key to use.
A
.B start
RPC is required before any others.    The possible replies are:
.RS
.TP
.B ok
start succeeded.
.TP
.B "error \fIstring\fP
where
.I string
is the reason.
.RE
.PD
.TP
.B read
get data from
.I factotum
to send to the other party.  The possible replies are:
.RS
.TP
.B ok
read succeeded, this is zero length message.
.TP
.B "ok \fIdata\fP
read succeeded, the data follows the space and is
unformatted.
.TP
.B "done
authentication has succeeded, no further RPC's are
necessary
.TP
.B "done haveai
authentication has succeeded, an
.B AuthInfo
structure (see
.IR factotum (2))
can be retrieved with an
.B authinfo
RPC
.TP
.B "phase \fIstring\fP
its not your turn to read, get some data from
the other party and return it with a write RPC.
.TP
.B "error \fIstring\fP
authentication failed,
.I string
is the reason.
.TP
.B "protocol not started
a
.B start
RPC needs to precede reads and writes
.TP
.B "needkey \fIattribute-value-list\fP
a key matching the argument is needed.
This will not appear if the
.B needkey
file is in use.
Otherwise, a suitable key can be written to
.B ctl
and after that,
authentication may proceed (ie, the read restarted).
.PD
.RE
.TP
.B "write \fIdata\fP
send data from the other party to
.IR factotum .
The possible replies are:
.RS
.TP
.B "ok
the write succeeded
.TP
.B "needkey \fIattribute-value-list\fP
see above
.TP
.B "toosmall \fIn\fP
the write is too short, get more data from the
other party and retry the write.
.I n
specifies the maximun total number of bytes.
.TP
.B "phase \fIstring\fP
its not your turn to write, get some data from
.I factotum
first.
.TP
.B "done
see above
.TP
.B "done haveai
see above
.RE
.TP
.B authinfo
retrieve the AuthInfo structure.  
The possible replies are:
.RS
.TP
.B "ok \fIdata\fP
.I data
is a marshaled form of the AuthInfo structure.
.TP
.B "error \fIstring\fP
where
.I string
is the reason for the error.
.PD
.RE
.TP
.B attr
retrieve the attributes used in the
.B start
RPC.
The possible replies are:
.RS
.TP
.B "ok \fIattribute-value-list\fP
.TP
.B "error \fIstring\fP
where
.I string
is the reason for the error.
.PD
.RE
.SS Protocols
.I Factotum
can support many authentication protocols, each implemented by a separate
module in the directory
.BR /dis/auth/proto .
Currently only a few are implemented in Inferno:
.PP
.B Infauth
is the Inferno public-key authentication protocol described by
.IR auth (6).
It requires a key with
.BR proto = infauth ,
and a
.B !authinfo
attribute providing Inferno authentication data as an S-expression (see
.IR 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
.I alpha
and
.IR p ,
selected by the signer when the key was generated.
The keys and certificates are represented as strings of the form produced by
.IR keyring-certtostr (2);
the parameter values are represented as binary in the form produced by
.B IPint.iptobytes
(see
.IR keyring-ipint (2)).
Normally
.B infauth
checks that the other party's key was signed by the signer in the
.B !authinfo
data, but
if the key has the attribute
.B anysigner
with non-zero integer value,
.B infauth
will accept keys signed by any signer.
The actual signer can be determined by inspecting the data
returned by the
.B authinfo
request;
the option is intended for use by services that support calls from many domains,
each with its own signer.
.PP
.BR P9sk1
is the shared-secret protocol used to authenticate to various Plan 9 services.
It requires a key with
.BR proto = p9sk1 ,
a
.B dom
attribute identifying the authentication domain, a
.B user
name valid in that domain, and either a
.B !password
or
.B !hex
attribute specifying the password or hexadecimal secret
to be used.
.B P9sk1
normally is invoked by Plan 9's general authentication protocol,
.BR p9any ,
which is supported by Inferno's
.IR factotum .
.PP
.B Pass
requires a key with
.B proto=pass
in addition to
.B user
and
.B !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.
.SH SOURCE
.B /appl/cmd/auth/factotum
.SH SEE ALSO
.IR factotum (2)