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):
            (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;
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;

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 succeeded; 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 authentication and that was successful, ai is a non-nil reference to an Authinfo value containing the agreed user IDs, a capability 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 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 protocol 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 reference 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 protocol. On error, the response is nil, and the system error string contains a diagnostic.

Factotum(4) represents keys as attribute value pairs in textual 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 conventions 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.

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 authentication 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 garbled, 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.