FACTOTUM(2)                                           FACTOTUM(2)

     NAME
          Factotum: attrtext, challenge, copyattrs, delattr, findattr,
          findattrval, getuserpassd, mount, open, parseattrs, proxy,
          publicattrs, takeattrs, respond, response, rpc, rpcattrs -
          client interface to factotum

     SYNOPSIS
          include "factotum.m";
          auth := load Factotum Factotum->PATH;

          Authinfo: adt{
              cuid: string;    # ID on caller
              suid: string;    # ID on server
              cap:  string;    # capability (only valid on server side)
              secret: array of byte;   # key for encryption
          };

          AuthRpcMax: con ...;

          init:          fn();
          mount:  fn(fd: ref Sys->FD, mnt: string, flags: int,
                      aname: string, keyspec: string): (int, ref Authinfo);

          getuserpasswd: fn(keyspec: string): (string, string);

          Challenge: adt {
              user:  string;      # user (some protocols)
              chal:  string;      # challenge string
          };

          challenge: fn(keyspec: string): ref Challenge;
          response:  fn(c: ref Challenge, resp: string): ref Authinfo;
          respond:   fn(chal: string, keyspec: string): (string, string);

          open:      fn(): ref Sys->FD;
          rpc:       fn(facfd: ref Sys->FD, verb: string, a: array of byte):
                        (string, array of byte);
          proxy:     fn(afd: ref Sys->FD, facfd: ref Sys->FD, arg: string):
                        ref Authinfo;
          rpcattrs:  fn(facfd: ref Sys->FD): list of ref Attr;

          Attr: adt {
              tag:    int;      # Aattr, Aval, or Aquery
              name:   string;
              val:    string;

              text:   fn(a: self ref Attr): string;
          };

          parseattrs:  fn(s: string): list of ref Attr;

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

     FACTOTUM(2)                                           FACTOTUM(2)

          copyattrs:   fn(l: list of ref Attr): list of ref Attr;
          delattr:     fn(l: list of ref Attr, n: string): list of ref Attr;
          takeattrs:   fn(l: list of ref Attr, names: list of string): list of ref Attr;
          findattr:    fn(l: list of ref Attr, n: string): ref Attr;
          findattrval: fn(l: list of ref Attr, n: string): string;
          publicattrs: fn(l: list of ref Attr): list of ref Attr;
          attrtext:    fn(l: list of ref Attr): string;

     DESCRIPTION
          Factotum interacts with an instance of the authentication
          agent factotum(4) to authenticate a client to a server.  It
          can also interact with Plan 9's factotum if that is in the
          name space (as well as or instead of factotum(4)).

          Factotum supports both the basic RPC interface to factotum
          and various high-level operations built on that.  The high-
          level functions will be described first.

          Init must be called before any other function.

          Mount is similar to Sys->mount (see sys-bind(2)), but uses
          factotum to authenticate, if the server requires it.
          Factotum->mount should be used instead of Sys->mount when
          mounting file servers that use attach(5) to authenticate.
          (If the server on fd does not require authentication,
          Factotum->mount simply calls Sys->mount.)  Mount returns
          (v,ai).  If the integer v is non-negative, the mount suc-
          ceeded; on error, v is negative, either the authentication
          or the mount failed, ai is nil, and the system error string
          contains a diagnostic.  If the server required authentica-
          tion and that was successful, ai is a non-nil reference to
          an Authinfo value containing the agreed user IDs, a capabil-
          ity for cap(3) that is valid only on the server, and an
          array of bytes containing a shared secret that can be used
          by client and server to create encryption and hashing keys
          for the conversation.

          Getuserpasswd returns a tuple (user,password) containing the
          values for the user and !password attributes of a factotum
          entry that has proto=pass and matches the given keyspec. The
          tuple values are nil if no entry matches or the caller lacks
          permission to see them.

          The pair of functions challenge and response give servers
          access to challenge/response protocols provided by factotum.
          All such authentication protocols are embedded in an
          application-level protocol such as FTP, IMAP, POP3 and so
          on, in a way specific to that protocol.  These functions
          calculate parameters for application-specific messages.

          A server calls challenge to get a challenge value to present
          to the user who will answer the challenge.  The server

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

     FACTOTUM(2)                                           FACTOTUM(2)

          verifies the user's response by calling response, which
          returns an Authinfo value (as described above) if the
          response is correct.  The specific challenge/response proto-
          col is selected by the proto attribute in the keyspec for
          challenge, which opens a connection to factotum, obtains a
          string representing a challenge value, and returns a refer-
          ence to a Challenge adt that gives the challenge and a user
          name.  Some protocols take the user name from a user
          attribute in the keyspec, and others negotiate it within the
          authentication protocol.  In the latter case, the user field
          of the resulting Challenge gives the name negotiated.

          In the other direction, a process uses respond to calculate
          the correct response to a given challenge.  Chal is the
          challenge presented by a server, and keyspec gives the
          attributes of the relevant key in the local factotum.
          Respond interacts with factotum and returns a tuple
          (response, user) that gives the response string to return to
          the server, and an optional user name, depending on the pro-
          tocol.  On error, the response is nil, and the system error
          string contains a diagnostic.

          Factotum(4) represents keys as attribute value pairs in tex-
          tual form, with space-separated fields.  A field can be a
          value-less attribute, an attribute=value pair, or attribute?
          to mark a required attribute with unknown value.  An
          attribute name that begins with an exclamation mark (!)  is
          to be considered hidden or secret.  Values containing white
          space or special characters can be quoted using the conven-
          tions of sh(1).

          Parseattrs parses a string s of that form into a list of
          Attr references.  Each Attr has a tag that identifies the
          value as Aattr (a value-less attribute), a Aval (an
          attribute-value pair), or Aquery (an attribute for which a
          value is needed).  Other operations include:

          copyattrs      Return a copy of attribute list l.

          delattr        Return a copy of l removing all attributes
                         with name n.

          takeattrs      Return the subset of list l that contains
                         only the attributes listed in names.

          findattr       Return a reference to the first Attr in l
                         with the name n.

          findattrval    Return the value of the first attribute in l
                         with name n; return nil if the attribute is
                         not found or has no value.

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

     FACTOTUM(2)                                           FACTOTUM(2)

          publicattrs    Return a copy of l in which all secret
                         attributes have been removed.

          attrtext       Return the textual representation of
                         attribute list l, acceptable to parseattrs.

          The low-level interfaces to factotum are as follows.

          Proxy links an authenticating server on afd with the
          factotum agent on facfd. Typically facfd is the result of
          calling Factotum->open, which is equivalent to

               sys->open("/mnt/factotum/rpc", Sys->ORDWR)

          Afd is a file descriptor that represents a connection to the
          service that requires authentication.  It is typically the
          result of sys-open(2), dial(2), or sys-fauth(2). Params
          gives any parameters for factotum, as a string containing
          space-separated attr=value pairs.  Proxy ferries messages
          between the server and factotum until the end of the
          selected authentication protocol.  If authentication failed,
          proxy returns nil; otherwise on success it always returns a
          non-nil reference to an Authinfo value with contents as
          above, but if the protocol does not supply that authentica-
          tion data, all the values are nil.

          Rpcattrs returns the initial attributes provided in the
          start request, and any others added later by the protocol.

          Rpc does one message exchange with the factotum on facfd. It
          writes a message containing the given verb and optional
          binary parameter a, and returns (v,a) where v is the
          response string from factotum and a is an optional binary
          parameter for that response.  Exceptionally, v is the string
          "rpc failure" if communication fails or a message is gar-
          bled, or "no key" if rpc cannot find a suitable key.  See
          factotum(4) for details of the protocol.

          AuthRpcMax is an integer constant giving the maximum size of
          a message in an rpc exchange.

     SOURCE
          /appl/lib/factotum.b

     SEE ALSO
          sys-bind(2), sys-fauth(2), factotum(4), attach(5)

     DIAGNOSTICS
          Functions that  return nil references on error also set the
          system error string.

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