20060303-partial

1 files changed, 717 insertions, 0 deletions

diff --git a/man/4/factotum b/man/4/factotum
new file mode 100644
index 00000000..867206b6
--- /dev/null
+++ b/man/4/factotum
@@ -0,0 +1,717 @@
+.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)