new man pages

1 files changed, 705 insertions, 0 deletions

diff --git a/man/man4/factotum.4 b/man/man4/factotum.4
new file mode 100644
index 00000000..777fe744
--- /dev/null
+++ b/man/man4/factotum.4
@@ -0,0 +1,705 @@
+.TH FACTOTUM 4
+.SH NAME
+factotum \- authentication agent
+.SH SYNOPSIS
+.B factotum
+[
+.B -DdkSun
+] [
+.B -a authaddr
+] [
+.B -s
+.I srvname
+] 
+.\" [
+.\" .B -m
+.\" .I mtpt
+.\" ]
+.PP
+.B factotum
+.B -g
+.IB attribute = value
+.B ...
+.IB attribute ?
+.B ...
+.\" .PP
+.\" .B auth/fgui
+.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
+presents 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, the
+authentication is mutual.
+Proof is accomplished using secret information kept by 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
+Plan 9's
+\fIauthsrv\fR(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
+supports the following protocols:
+.TF mschap
+.TP
+.B p9any
+a metaprotocol used to negotiate which actual protocol to use.
+.TP
+.B p9sk1
+a Plan 9 shared key protocol.
+.TP
+.B p9sk2
+a variant of
+.B p9sk1.
+.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, the file
+.BR <mtpt>/ndb ,
+and finally the network database in
+.BR /lib/ndb .
+.TP
+.B \-m
+specifies the mount point to use, by default
+.BR /mnt .
+.TP
+.B \-s
+specifies the service name to use.
+Without this option,
+.I factotum
+does not create a service file in
+.BR /srv .
+.TP
+.B \-D
+turns on 9P tracing, written to standard error.
+.TP
+.B \-d
+turns on debugging, written to standard error.
+.TP
+.B \-g
+causes the agent to prompt for the key, write it
+to the
+.B ctl
+file, and exit.
+The agent will prompt for values for any of the
+attributes ending with a question mark
+.RB ( ? )
+and will append all the supplied
+.I attribute = value
+pairs.  See the section on key templates below.
+.TP
+.B \-n
+don't look for a secstore.
+.TP
+.B \-S
+indicates that the agent is running on a
+cpu server.  On starting, it will attempt to get a
+.B 9psk1
+key from NVRAM using
+.B readnvram
+(see
+.IR authsrv (3)),
+prompting for anything it needs.
+It will never subsequently prompt for a
+key that it doesn't have.
+This option is typically used by
+the kernel at boot time.
+.TP
+.B \-k
+causes the NVRAM to be written.
+It is only valid with the
+.B \-S
+option.
+This option is typically used by
+the kernel at boot time.
+.TP
+.B \-u
+causes the agent to prompt for user
+id and writes it to
+.BR /dev/hostowner .
+It is mutually exclusive with
+.B \-k
+and
+.BR \-S .
+This option is typically used by
+the kernel at boot time.
+.PD
+.\" .PP
+.\" .I 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
+.\" .B confirm
+.\" and
+.\" .BR needkey .
+.\" For each requests, it unhides itself 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.  An attribute whose name begins with an exclamation point
+.RB ( ! )
+does not appear when reading the
+.B ctl
+file.
+The required attributes depend on the authentication protocol.
+.PP
+.BR P9sk1 ,
+.BR p9sk2 ,
+and
+.BR p9cr
+all require 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.  Here is an example:
+.PP
+.EX
+    proto=p9sk1 dom=avayalabs.com user=presotto !password=lucent
+.EE
+.PP
+.BR Apop ,
+.BR cram ,
+.BR chap ,
+and
+.BR mschap ,
+require a key with a
+.B proto
+attribute whose value matches the protocol,
+in addition to
+.BR server ,
+.BR user ,
+and
+.B !password
+attributes; 
+e.g.
+.PP
+.EX
+    proto=apop server=mit.edu user=rsc !password=nerdsRus
+.EE
+Vnc is similar but does not require a
+.B user
+attribute.
+.PP
+.B Pass
+requires a key with
+.B proto=pass
+in addition to
+.B user
+and
+.B !password
+attributes; e.g.
+.PP
+.EX
+    proto=pass user=tb !password=does.it.matter
+.EE
+.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.
+.PP
+All keys can have additional attibutes that act either as comments
+or as selectors to distinguish them in the
+.IR auth (2)
+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.
+.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
+.I factotum
+such as
+.B auth_proxy
+and
+.B auth_challenge
+(see
+.IR auth (3))
+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 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 mesages are:
+.TP
+.B "key \fIattribute-value-list\fP
+add a new key.  This will replace any old key whose
+public, i.e. non ! attributes, match.
+.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 authsrv (3)).
+.PP
+The RPC protocol is normally embodied by one of the
+routines in
+.IR auth (3).
+We describe it here should anyone want to extend
+the library.
+.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 auth (3))
+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 argument
+may be passed as an argument to
+.I factotum
+.B -g
+in order to prompt for a key.  After that, the
+authentication may proceed, i.e., 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
+.SH SOURCE
+.B \*9/src/cmd/factotum