SECURITY-AUTH(2) SECURITY-AUTH(2)
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 infor-
mation 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 authen-
ticated connection cannot be established, or the client's
chosen algorithm is not listed, server returns a nil file
Page 1 Plan 9 (printed 10/28/25)
SECURITY-AUTH(2) SECURITY-AUTH(2)
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)
Page 2 Plan 9 (printed 10/28/25)