include "keyring.m";
include "security.m";
auth := load Auth Auth->PATH;

init:   fn(): string;
client: fn(alg: string, ai: ref Keyring->Authinfo,
            fd: ref Sys->FD): (ref Sys->FD, string);
server: fn(algs: list of string, ai: ref Keyring->Authinfo,
            fd: ref Sys->FD, setid: int): (ref Sys->FD, string);

Init must be called before using any other functions in Auth; it returns nil if successful, and a diagnostic message otherwise.

Client authenticates a connection with the server on fd using the authentication data in ai. If successful, and alg is neither nil nor the value "none", client will set the connection to digest or encrypt the data, using the digest or encryption algorithm specified in alg. It returns the file descriptor for the connection, and a string with information about the connection. If an authenticated connection cannot be established, client returns a nil file descriptor and an error message.

Server authenticates a client connection fd, as described in keyring-auth(2), using the server's authentication data in ai. If successful, and the client requested the use of a digest or encryption algorithm, and that algorithm is listed in algs, server enables the security layer ssl(3) using the selected algorithm. Furthermore, if setid is non-zero, the current user name is set to the newly authenticated name. Server returns a file descriptor for the connection, and a string with information about the connection. If an authenticated connection cannot be established, or the client's chosen algorithm is not listed, server returns a nil file descriptor and an error message.

Any string acceptable to ssl(3), including "clear", can be given as an alg to client, or listed in algs for server. Furthermore, the special string "none" tells both functions that ssl(3) should not be used at all on a connection.

	au := load Auth Auth->PATH;
	err := au->init();
	if(err != nil){
		sys->fprint(stderr, "mount: %s\n", err);
		exit;
	}
	fd: ref Sys->FD;
	(fd, err) = au->client("none", ai, c.dfd);
	if(fd == nil){
		sys->fprint(stderr, "mount: authentication failed: %s\n", err);
		exit;
	}
	dir := hd argv;
	ok = sys->mount(fd, dir, flags, "");
	if(ok < 0)
		sys->fprint(stderr, "mount: %r\n");

The following example from /appl/lib/styxd.b shows server-side use; note that readauthinfo is called first to fetch the authentication data to pass to server.

	kr := load Keyring Keyring->PATH;
	...
	ai := kr->readauthinfo("/usr/"+user+"/keyring/default");
	auth->init();
	(fd, info_or_err) := auth->server(argv, ai, stdin, 1);
	if(fd == nil){
		sys->fprint(stderr, "styxd: %s\n", info_or_err);
		exit;
	}
	sys->pctl(Sys->FORKNS, nil);
	if(sys->export(fd, Sys->EXPASYNC) < 0)
		sys->fprint(stderr, "styxd: file export: %r\n");