NAME

Factotum: mount, proxy, rpc - 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):
            (int, ref Authinfo);
getuserpasswd:	fn(keyspec: string): (string, string);
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;

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)).

Init must be called before any other function.

Mount is similar to Sys->mount (see sys-bind(1)), 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 auth(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.

Proxy links an authenticating server on afd with the factotum agent on facfd. Typically facfd is the result of

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

Afd is typically the result of sys-open(2), sys-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.

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.

SOURCE

/appl/lib/factotum.b

SEE ALSO

sys-bind(2), sys-fauth(2), factotum(4), auth(5)

FACTOTUM(2)

Rev:  Mon Aug 01 10:33:23 GMT 2005