FACTOTUM(4)                                           FACTOTUM(4)

     NAME
          factotum, fgui, userpasswd - authentication agent

     SYNOPSIS
          auth/factotum [ -DdknpuS ] [ -a asaddr ] [ -s srvname ] [ -m
          mtpt ]

          auth/factotum -g attribute=value ... attribute?  ...

          auth/fgui

          auth/userpasswd fmt

     DESCRIPTION
          Factotum is a user-level file system that acts as the
          authentication agent for a user.  It does so by managing a
          set of keys. A key is a collection of information used to
          authenticate a particular action.  Stored as a list of
          attribute=value pairs, a key typically contains a user, an
          authentication domain, a protocol, and some secret data.

          Factotum presents a two level directory.  The first level
          contains a single directory factotum, which in turn con-
          tains:

          rpc      each open represents a new private channel to
                   factotum
          proto    when read lists the protocols available
          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 `?'  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, 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 pos-
          sessing the same user id as it.  For select protocols such
          as p9sk1 and dp9ik it can also act as a client for other
          processes provided its user id may speak for the other pro-
          cess' user id (see authsrv(6)). Factotum can act in the role

     Page 1                       Plan 9             (printed 3/28/24)

     FACTOTUM(4)                                           FACTOTUM(4)

          of server for any process.

          Factotum's structure is independent of any particular
          authentication protocol.  Factotum supports the following
          protocols:

          p9any     a metaprotocol used to negotiate which actual pro-
                    tocol to use.
          p9sk1     legacy Plan 9 shared key protocol described in
                    authsrv(6)'s ``Ticket Service'' and ``P9sk1'' sec-
                    tions.
          dp9ik     extended version of p9sk1 that adds password
                    bruteforce resistance and forward secrecy (see
                    authsrv(6)'s ``Password authenticated key
                    exchange'' and ``Dp9ik'' sections).
          p9cr      legacy Plan 9 protocol that can use either p9sk1
                    keys or SecureID tokens.
          apop      the challenge/response protocol used by POP3 mail
                    servers.
          cram      the challenge/response protocol also used by POP3
                    mail servers.
          chap      the challenge/response protocols used by PPP and
                    PPTP.
          mschap    a proprietary Microsoft challenge/response proto-
                    col also used by PPP, PPTP and CIFS.
          mschapv2  version two of Microsofts challenge/response pro-
                    tocol used by WPA.
          mschap2   Microsofts NTLMv2 challenge/response protocol used
                    by CIFS.
          rsa       RSA public key decryption, used by SSH and TLS.
          pass      passwords in the clear.
          vnc       vnc(1)'s challenge/response.
          wpapsk    WPA passwords for wireless ethernet cards.

          The options are:

          -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 <mtpt>/ndb, and finally the network
               database in /lib/ndb.

          -m   specifies the mount point to use, by default /mnt.

          -s   specifies the service name to use.  Without this
               option, factotum does not create a service file in
               /srv.

          -D   turns on 9P tracing, written to standard error.

          -d   turns on debugging, written to standard error.

     Page 2                       Plan 9             (printed 3/28/24)

     FACTOTUM(4)                                           FACTOTUM(4)

          -g   causes the agent to prompt for the key, write it to the
               ctl file, and exit.  The agent will prompt for values
               for any of the attributes ending with a question mark
               (?)  and will append all the supplied attribute = value
               pairs.  See the section on key templates below.

          -n   don't look for a secstore.

          -S   indicates that the agent is running on a CPU server.
               On starting, it will attempt to get p9sk1 and dp9ik
               keys from NVRAM using readnvram (see authsrv(2)),
               prompting for anything it needs.  It will never subse-
               quently prompt for a key that it doesn't have.  This
               option is typically used by the kernel at boot time.

          -k   causes the NVRAM to be written.  It is only valid with
               the -S option.  This option is typically used by the
               kernel at boot time.

          -u   causes the agent to prompt for user id and writes it to
               /dev/hostowner.  It is mutually exclusive with -k and
               -S.  This option is typically used by the kernel at
               boot time.

          -p   causes the agent not to mark itself `private' via
               proc(3), so that it can be debugged.  It is implied by
               -d.

          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 confirm and needkey.
          For each requests, it unhides itself and waits for user
          input.  See the sections on key confirmation and key prompt-
          ing below.

          Userpasswd queries and prints a cleartext user/password pair
          from factotum for the proto=pass key tuple specified in fmt.
          This can be used by shell scripts to do cleartext password
          authentication.

        Key Tuples
          A key tuple is a space delimited list of attribute=value
          pairs.  An attribute whose name begins with an exclamation
          point (!)  does not appear when reading the ctl file.  The
          required attributes depend on the authentication protocol.

          Dp9ik, p9sk1 and p9cr all require a key with proto=dp9ik or
          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 hex-
          adecimal secret to be used.  Here is an example:

     Page 3                       Plan 9             (printed 3/28/24)

     FACTOTUM(4)                                           FACTOTUM(4)

              proto=dp9ik dom=9front user=glenda !password=secret

          Apop, cram, chap, and mschap, require a key with a proto
          attribute whose value matches the protocol, in addition to
          server, user, and !password attributes; e.g.

              proto=apop server=mit.edu user=rsc !password=nerdsRus
          Vnc is similar but does not require a user attribute.

          Pass requires a key with proto=pass in addition to user and
          !password attributes; e.g.

              proto=pass user=tb !password=does.it.matter

          Rsa requires a key with proto=rsa in addition to all the hex
          attributes defining an RSA key: ek, n, !p, !q, !kp, !kq,
          !c2, and !dk.  By convention, programs using the RSA proto-
          col also require a service attribute set to ssh or tls.

          All keys can have additional attributes that act either as
          comments or as selectors to distinguish them in the auth(2)
          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,
          `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

          speakfor
               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 disabled=by.factotum when they fail during
          certain authentication protocols (in particular, the Plan 9
          ones).

          Whenever factotum runs as a server, it must have dp9ik or
          p9sk1 keys in order to communicate with the authentication

     Page 4                       Plan 9             (printed 3/28/24)

     FACTOTUM(4)                                           FACTOTUM(4)

          server for validating passwords and challenge/responses of
          other users.

        Key Templates
          Key templates are used by routines that interface to
          factotum such as auth_proxy and auth_challenge (see auth(2))
          to specify which key and protocol to use for an authentica-
          tion.  Like a key tuple, a key template is also a list of
          attribute=value pairs.  It must specify at least the proto-
          col 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:

          attr=val  The attribute attr must exist in the key and its
                    value must exactly match val

          attr?     The attribute attr must exist in the key but its
                    value doesn't matter.

          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:

          attr=val  This pair must remain unchanged

          attr?     This attribute needs a value

          attr      The pair must remain unchanged

        Control and Key Management
          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, i.e. non ! attributes, match.

          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.

          By default when factotum starts it looks for a secstore(1)
          account on $auth for the user and, if one exists, prompts
          for a secstore password in order to fetch the file factotum,
          which should contain control file commands.  An example

     Page 5                       Plan 9             (printed 3/28/24)

     FACTOTUM(4)                                           FACTOTUM(4)

          would be
            key dom=x.com proto=p9sk1 user=boyd !hex=26E522ADE2BBB2A229
            key proto=rsa service=ssh size=1024 ek=3B !dk=...
          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.

        Confirming key use
          The confirm file provides a connection from factotum to a
          confirmation server, normally the program auth/fgui. When-
          ever a key with the confirm attribute is used, factotum
          requires confirmation of its use.  If no process has 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:

          confirm tag=tagno <key template>

          The reply, written back to confirm, consists of string:

          tag=tagno answer=xxx

          If xxx is the string yes then the use is confirmed and the
          authentication will proceed.  Otherwise, it fails.

          Confirm is exclusive open and can only be opened by a pro-
          cess with the same user id as factotum.

        Prompting for keys
          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 miss-
          ing 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 pro-
          cess with the same user id as factotum.

        The RPC Protocol
          Authentication is performed by

          1)   opening rpc

     Page 6                       Plan 9             (printed 3/28/24)

     FACTOTUM(4)                                           FACTOTUM(4)

          2)   setting up the protocol and key to be used (see the
               start RPC below),

          3)   shuttling messages back and forth between factotum and
               the other party (see the read and write RPC's) until
               done

          4)   if successful, reading back an AuthInfo structure (see
               authsrv(2)).

          The RPC protocol is normally embodied by one of the routines
          in auth(2). We describe it here should anyone want to extend
          the library.

          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 attributes 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 struc-
                    ture (see auth(2)) can be retrieved with an
                    authinfo RPC

               phase string

     Page 7                       Plan 9             (printed 3/28/24)

     FACTOTUM(4)                                           FACTOTUM(4)

                    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 argu-
                    ment may be passed as an argument to factotum -g
                    in order to prompt for a key.  After that, the
                    authentication may proceed, i.e., the read res-
                    tarted.

          write data
               send data from the other party to factotum. The possi-
               ble 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 struc-
                    ture.

               error string
                    where string is the reason for the error.

          attr retrieve the attributes used in the start RPC.  The
               possible replies are:

     Page 8                       Plan 9             (printed 3/28/24)

     FACTOTUM(4)                                           FACTOTUM(4)

               ok attribute-value-list

               error string
                    where string is the reason for the error.

     SOURCE
          /sys/src/cmd/auth/factotum

     SEE ALSO
          authsrv(6)

     Page 9                       Plan 9             (printed 3/28/24)