KEYRING-AUTH(2) KEYRING-AUTH(2)
NAME
auth, readauthinfo, writeauthinfo - authenticate a
connection
SYNOPSIS
include "keyring.m";
keyring := load Keyring Keyring->PATH;
auth: fn(fd: ref Sys->FD, info: ref Authinfo, setid: int)
: (string, array of byte);
readauthinfo: fn(filename: string): ref Authinfo;
writeauthinfo: fn(filename: string, info: ref Authinfo): int;
DESCRIPTION
Auth performs mutual authentication over a network connec-
tion, usually between a client and a server. The function
is symmetric: each party runs it on their end of the connec-
tion. Info holds the public key of a certifying authority
(PKca), the private key of the user (SKu), the public key
(PKu) of the user signed by the certifying authority
(CERTu), and Diffie-Hellman parameters (alpha, p).
Auth returns a string and a byte array. If the byte array
is nil then the authentication has failed and the string is
an error message. If the byte array is non-nil, it repre-
sents a secret shared by the two communicating parties, and
the string names the party at the other end of the connec-
tion.
If the authentication is successful and setid is non-zero
then auth attempts to write the name of the party at the
other end of the connection into /dev/user (see cons(3)); no
error is generated if that does not succeed. If the authen-
tication is not successful and setid is non-zero, auth
writes the name nobody into /dev/user.
The authentication protocol is based on the Station-to-
Station protocol. In the following, the parties are labelled
0 and 1. Sig0(x) is x signed with 0's private key.
0 → 1 alpha**r0 mod p, CERTu0, PKu0
1 → 0 alpha**r1 mod p, CERTu1, PKu1
0 → 1 sig0(alpha**r0 mod p, alpha**r1 mod p)
1 → 0 sig1(alpha**r0 mod p, alpha**r1 mod p)
At this point both 0 and 1 share the secret alpha**(r0*r1)
which is returned in the byte array. Amongst other things,
it can be the secret to digest or encrypt a conversation
(see security-ssl(2)).
Readauthinfo reads a representation of an Authinfo from a
Page 1 Plan 9 (printed 12/21/24)
KEYRING-AUTH(2) KEYRING-AUTH(2)
file. It returns nil if there is a read error or a conver-
sion error; it returns a reference to the Authinfo other-
wise.
Writeauthinfo writes a representation of info to a file. It
returns -1 if the write operation fails, 0 otherwise.
FILES
/usr/user/keyring The conventional directory for
storing Authinfo files
/usr/user/keyring/default The key file normally used by
server programs
/usr/user/keyring/net!server The key file normally used by
clients for a given server
SOURCE
/interp/keyring.c
Page 2 Plan 9 (printed 12/21/24)