.TH KEYRING-AUTH 2.SH NAMEkeyring: auth, readauthinfo, writeauthinfo \- authenticate a connection.SH SYNOPSIS.EXinclude "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;.EE.SH DESCRIPTION.B Authperforms mutual authentication over a network connection, usually between a client and a server.The function is symmetric: each party runs it on their end of the connection..I Infoholds the public key of a certifying authority.RB ( PKca ),the private key of the user.RB ( SKu ),the public key.RB ( PKu )of the user signed by the certifying authority.RB ( CERTu ),and Diffie-Hellman parameters.RB ( alpha ,.BR p )..PP.B Authreturns 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 represents a secret shared by the two communicating parties,and the string names the party at the other end of the connection..PPIf the authentication is successful and.I setidis non-zero then.B authattempts to write the name of the party at the other end of the connection into.B /dev/user(see.IR cons (3));no error is generated if that does not succeed.If the authentication is not successful and.I setidis non-zero,.B authwrites the name.B nobodyinto.BR /dev/user ..PPThe authentication protocol is based on the Station-to-Station protocol. In the following, the parties are labelled 0 and 1..BI Sig0( x )is.I xsigned with 0's private key..IP.EX0 → 1  alpha**r0 mod p, CERTu0, PKu01 → 0  alpha**r1 mod p, CERTu1, PKu10 → 1  sig0(alpha**r0 mod p, alpha**r1 mod p)1 → 0  sig1(alpha**r0 mod p, alpha**r1 mod p).EE.PPAt this point both 0 and 1 share the secret.B "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.IR security-ssl (2))..PP.B Readauthinforeads a representation of an.B Authinfofrom a file.It returns nil if there is a read error or a conversion error;it returns a reference to the.B Authinfootherwise..PP.B Writeauthinfowrites a representation of.I infoto a file. It returns -1 if the write operation fails, 0 otherwise..SH FILES.TF /usr/user/keyring/defaultxxx.TP.BI /usr/ user /keyringThe conventional directory for storing.B Authinfofiles.TP.BI /usr/ user /keyring/defaultThe key file normally used by server programs.TP.BI /usr/ user /keyring/ net ! serverThe key file normally used by clients for a given.I server.SH SOURCE.B /libinterp/keyring.c