.TH AUTH 6
.SH NAME
fsauth, rexauth, chal, changekey \- authentication services
.SH DESCRIPTION
This manual page describes the
.IR "authentication services" :
the protocols used to authorize connections, confirm the identities
of users and machines, and maintain the associated databases.
The machine that provides these services is called the
.I authentication server
and may be a stand-alone machine or a general-use machine such as a CPU server.
The network database holds for each public machine, such as a CPU server or
file server, the name of the authentication server that machine uses.
.PP
There are four authentication services.
Each is executed by making a network call from the
machine wishing authentication to the authentication server
and exchanging messages.
The services are:
.TF xxxxxxx
.TP
.I fsauth
authenticate file system attaches
.TP
.I rexauth
authenticate remote execution from a Plan 9 machine
.TP
.I chal
authenticate connections from a non-Plan 9 machine using a SecureNet box
(see
.IR securenet (8))
.TP
.I changekey
change the key for a user or client.
.PP
Multiple
.I fsauth
requests may be processed on a single
connection to the authentication server.
The other protocols accept only one request per call.
.PP
When a client calls another machine, say a file server,
using the 9P protocol, the file server receives a
.B Tauth
message containing information about the user making the call
(see
.IR auth (5)).
The file server exchanges some messages with the authentication server
using the
.I fsauth
protocol described below.
It then returns an
.B Rauth
message to the client containing a
.I ticket
to be used by the client in
the subsequent
.B Tattach
message
(see
.IR attach (5));
that ticket guarantees that the user requesting the service is
the one validated by the authentication server.
.PP
In describing the protocols, the following notation is used.
.PD 0
.IP A
The authentication server.
.IP S
A CPU server or file server.
.IP C
A client connecting to S.
When any of these appears as part of a message,
it refers to the textual name of the agent padded with zeros
to a total of
.B NAMELEN
bytes.
.TP
.RI K x
The
seven byte authentication key of
.IR x ;
.I x
is either S or C.
Servers keep a private copy of their keys, typically in non-volatile RAM,
and encrypt using the library functions
.IR encrypt (2)
and
.I decrypt.
Clients keep a copy of the current user's key in the file
.BR #c/key
and encrypt using the file
.B #c/crypt
(see
.IR cons (3)).
.IP K'C
C's
.I network key,
stored in C's SecureNet box.
Encryption with K'C is done with the algorithm described in
.IR securenet (8).
KC may also be used in place of K'C to execute the
.I chal
protocol without a SecureNet box;
in this case, the
.I netcrypt
routine is used for encryption.
In either case the result of the encryption is a variable length text string,
to be transmitted with its terminating NUL.
.IP KT
A
.I ticket key,
a random number stored in a ticket.
.TP
.IR x PC
A password for the client:
a 10 byte NUL-terminated string.
The character
.I x
is either
.I o
for an old password or
.I n
for a new one.
.TP
.RI Ch x
A seven byte challenge made by
.IR x ;
.I x
is one of A, S, or C.
.IP NetCh
A NUL-terminated string of between 1 and 6 digits
for encryption using K'C.
NetCh is a challenge generated by A and is transmitted
as a variable length NUL-terminated string.
.IP Kx{s}
Braces denote encryption.
Kx{s} is the result of encrypting
.I s
using key Kx.
.IP E
An error message
.B ERRLEN
bytes long.
.PD
.PP
Arrows indicate communication.
The authentication server communicates only with a server,
so a communication between A and C indicates that S
forwards the message uninterpreted.
.PP
Consider the
.I fsauth
protocol to validate a connection to a file server.
Here is the concise notation of the protocol; following that
is a prose description of its execution:
.PP
.PD 0
.I Fsauth
.TF xxxxxxx
.TP
[1] C\^\(->\^S
KC{FScchal, ChC, S}, C
.TP
[2] S\^\(->\^A
KS{FSschal, ChS, C, KC{FScchal, ChC, S}}, S
.TP
[3] A\^\(->\^S
KS{FSok, ChS, KC{FSctick, ChC, KT, KS{FSstick, ChS, KT}}}
.TP
or
.TP
[4] A\^\(->\^S
KS{FSerr, ChS, E}
.TP
[5] S\^\(->\^C
KC{FSctick, ChC, KT, KS{FSstick, ChS, KT}}
.TP
[6] C\^\(->\^S
KS{FSstick, ChS, KT}
.PD
.PP
[1] The client prepares a string containing an initial
byte with value
.B FScchal
(defined in
.BR <auth.h> ),
a seven-byte random string, ChC,
and the name of the server it is calling, e.g.
.BR kremvax ,
padded with zeros to
.B NAMELEN
bytes, for a total of
.RB 1+7+ NAMELEN =36
bytes.
If the client does not care which file system it attaches to,
it can substitute the string
.B "any"
for the name of the server.
It calls
.IR encrypt (2)
to encrypt this string using the password typed by the user at
login time and stored in
.B #c/key
(KC).
Next the client prepares a
.B Tauth
message (see
.IR auth (5)):
.B chal
is set to the result of the encryption (KC{FScchal,\^ChC,\^S}) and
.B uid
to the name of the user placing the call (C).
This message is transmitted to the server, S.
.PP
[2] The server prepares a string containing an initial byte with value
.BR FSschal ,
another 7-byte random string (ChS),
the name of the client (C),
and the contents of the
.B chal
field of the
.B Tauth
message.
It encrypts this using the server's key (KS) and appends its own name to
the 2*36=72 resulting bytes and
sends the total
.RB 72+ NAMELEN =100
bytes to the authentication server.
.PP
The authentication server responds with one of two results, both
encrypted with the server's key.
[3] If the authentication is approved,
the (decrypted) result contains a byte with value
.BR FSok ,
the server's challenge (ChS),
and a thirty-byte string, called
.I chal,
encrypted with the client's key, to be
returned to the client (KC{FSctick,\^ChC,\^KT,KS{FSstick,\^ChS,\^KT}}).
[4] If the authentication is not approved,
the result contains a byte with value FSerr,
the server challenge, and an error message.
.PP
[5] The server decrypts the response and sends either an
.B Rauth
message with the
.B chal
field set to the
.I chal
string or an
.B Rerror
message containing the error describing why authentication failed.
(The error case is not shown in the concise form; it is outside the
authentication protocol.)
.PP
[6] If authentication succeeds, the client decrypts the
.B chal
field of the
.B Rauth
and extracts the 15-byte long ticket (KS{FSstick,\^ChS,\^KT}).
It places that in the
.B auth
field of the
.B Tattach
message it sends to establish the connection to the server.
.PP
In the remaining protocol descriptions, the bytes transmitted in
the communications are exactly as presented in the concise notation.
.PP
.I Rexauth
.PD 0
.TF xxxxxxx
.TP
[1] S\^\(->\^C
KS{RXschal, ChS}
.TP
[2] C\^\(->\^A
KC{KS{RXschal, ChS}, S, RXcchal, ChC}, C
.TP
[3] A\^\(->\^C
KC{KS{RXstick, ChS, C, KC}, RXctick, ChC}
.TP
[4] C\^\(->\^S
KS{RXstick, ChS, C, KC}
.PD
.PP
[1] The client C calls the (CPU) server,
which recognizes the incoming call and
reads the already-encrypted string KS{RXschal,ChS} from the file
.B #c/chal
and transmits it to C.
.B RXschal
is a single byte identifying the message type.
.PP
[2] The client encapsulates the message in a larger message containing
the server name (S) , an
.B RXcchal
byte, a client challenge (ChC), all encrypted, and the client name (C)
(KC{KS{RXschal,\^ChS},\^S,\^RXcchal,\^ChC},\^C).
This message is sent to S which forwards it to the authentication server A.
.PP
[3] The authentication server forms a new message
(KC{KS{RXstick,\^ChS,\^C,\^KC},\^RXctick,\^ChC})
and sends it through the server to the client.
.PP
[4] The client decrypts this message and extracts a ticket
(KS{RXstick,\^ChS,\^C,\^KC}) which it sends to the server.
The ticket contains the client key (KC) so the server may
validate further requests for the client from the server.
.PP
.I Chal
.PD 0
.TF xxxxxxx
.TP
[1] S\^\(->\^A
C, S, KS{RXschal, ChS}
.TP
[2] A\^\(->\^C
NetCh
.TP
[3] C\^\(->\^A
K'C{NetCh}
.TP
[4] A\^\(->\^S
KS{RXstick, ChS, C, KC}
.PD
.PP
The
.I chal
protocol is closely related to
.I rexauth.
The main difference [2] is that the authentication server sends to the
client a challenge (NetCh) to be encrypted by a SecureNet box.
The result is returned [3] to the authentication server.
The challenge and response are variable-length NUL-terminated strings of
digits.
The rest of the protocol is isomorphic to
.I rexauth.
.PP
.I Changekey
.PD 0
.TF xxxxxxx
.TP
[1] A\^\(->\^C
ChA
.TP
[2] C\^\(->\^A
C, KC{CKcchal, ChA, oPC, nPC}
.TP
[3] A\^\(->\^C
password changed
.TP
or
.TP
[4] A\^\(->\^C
E
.PD
.PP
This protocol is run directly between a user and the authentication server
to change the key for a user;
no other server is involved.
.PP
[1] The authentication server sends a challenge directly to the client.
.PP
[2] The client constructs a message containing the name (C)
and an encrypted string holding a
.B CKcchal
byte, the challenge, the old password for the client (oPC) and
the new password (nPC).
It returns this to the authentication server.
.PP
[3] If the change is accepted the authentication server returns
the text string
.B password
.BR changed .
.PP
[4] Otherwise, it returns an error string (E).
.SH "SEE ALSO"
.IR auth (2),
.IR encrypt (2),
.IR intro (5),
.IR auth (5)
.SH BUGS
The
.I rexauth
and
.I chal
protocols should create a new key for the server to hold on behalf
of the client.