123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728 |
- .TH FACTOTUM 4
- .SH NAME
- factotum, fgui \- authentication agent
- .SH SYNOPSIS
- .B auth/factotum
- [
- .B -DdknpuS
- ] [
- .B -a asaddr
- ] [
- .B -s
- .I srvname
- ] [
- .B -m
- .I mtpt
- ]
- .PP
- .B auth/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 a two level directory. The first
- level contains a single directory
- .BR factotum ,
- which in turn contains:
- .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
- .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
- 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 described in
- .IR authsrv (6)'s
- ``File Service'' section.
- .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, 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 p9sk1
- key from NVRAM using
- .B readnvram
- (see
- .IR authsrv (2)),
- 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.
- .TP
- .B \-p
- causes the agent not to mark itself `private'
- via
- .IR proc (3),
- so that it can be debugged.
- It is implied by
- .BR \-d .
- .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 attributes 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,
- .LR 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 speakfor
- 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
- .I factotum
- such as
- .B auth_proxy
- and
- .B auth_challenge
- (see
- .IR auth (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 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, 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 (2)).
- .PP
- The RPC protocol is normally embodied by one of the
- routines in
- .IR auth (2).
- 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 attributes 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 (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 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 /sys/src/cmd/auth/factotum
|