NAME

Auth: init, client, server - authenticated connections between client and server

SYNOPSIS

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

DESCRIPTION

Auth establishes authenticated connections using the station to station protocol described in auth(6). It encapsulates the use of the primitives of keyring-auth(2) and security-ssl(2) for the particular case where the stations play the rôles of `client' and `server'. The underlying primitives must still be accessed directly in some cases, for instance when completely symmetric authentication is needed between peers.

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.

EXAMPLE

This selection from /appl/cmd/mount.b illustrates client-side use.

	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");

SOURCE

/appl/lib/auth.b

SEE ALSO

keyring-auth(2), security-ssl(2), ssl(3), auth(6)

SECURITY-AUTH(2 )

Rev:  Tue Mar 31 02:42:39 GMT 2015