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 12/23/24) 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 12/23/24)