AUTH(6) AUTH(6)
NAME
fsauth, rexauth, chal, changekey - authentication services
DESCRIPTION
This manual page describes the authentication services: the
protocols used to authorize connections, confirm the identi-
ties of users and machines, and maintain the associated
databases. The machine that provides these services is
called the 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.
There are four authentication services. Each is executed by
making a network call from the machine wishing authentica-
tion to the authentication server and exchanging messages.
The services are:
fsauth authenticate file system attaches
rexauth authenticate remote execution from a Plan 9 machine
chal authenticate connections from a non-Plan 9 machine
using a SecureNet box (see securenet(8))
changekey
change the key for a user or client.
Multiple fsauth requests may be processed on a single con-
nection to the authentication server. The other protocols
accept only one request per call.
When a client calls another machine, say a file server,
using the 9P protocol, the file server receives a Tauth mes-
sage containing information about the user making the call
(see auth(5)). The file server exchanges some messages with
the authentication server using the fsauth protocol
described below. It then returns an Rauth message to the
client containing a ticket to be used by the client in the
subsequent Tattach message (see attach(5)); that ticket
guarantees that the user requesting the service is the one
validated by authentication server.
In describing the protocols, the following notation is used.
A The authentication server.
S A CPU server or file server.
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 NAMELEN bytes.
Kx The seven byte authentication key of x; x is either S
or C. Servers keep a private copy of their keys, typi-
cally in non-volatile RAM, and encrypt using the
library functions encrypt(2) and decrypt. Clients keep
a copy of the current user's key in the file #c/key and
encrypt using the file #c/crypt (see cons(3)).
Page 1 Plan 9 (printed 4/25/24)
AUTH(6) AUTH(6)
K'C C's network key, stored in C's SecureNet box. Encryp-
tion with K'C is done with the algorithm described in
securenet(8). KC may also be used in place of K'C to
execute the chal protocol without a SecureNet box; in
this case, the netcrypt routine is used for encryption.
In either case the result of the encryption is a vari-
able length text string, to be transmitted with its
terminating NUL.
KT A ticket key, a random number stored in a ticket.
A password for the client: a 10 byte NUL-terminated
string. The character x is either o for an old pass-
word or n for a new one.
Chx A seven byte challenge made by x; x is one of A, S, or
C.
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.
Kx{s}
Braces denote encryption. Kx{s} is the result of
encrypting s using key Kx.
E An error message ERRLEN bytes long.
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.
Consider the 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:
Fsauth
[1] C->S KC{FScchal, ChC, S}, C
[2] S->A KS{FSschal, ChS, C, KC{FScchal, ChC, S}}, S
[3] A->S KS{FSok, ChS, KC{FSctick, ChC, KT, KS{FSstick, ChS,
KT}}}
or
[4] A->S KS{FSerr, ChS, E}
[5] S->C KC{FSctick, ChC, KT, KS{FSstick, ChS, KT}}
[6] C->S KS{FSstick, ChS, KT}
[1] The client prepares a string containing an initial byte
with value FScchal (defined in <auth.h>), a seven-byte ran-
dom string, ChC, and the name of the server it is calling,
e.g. kremvax, padded with zeros to NAMELEN bytes, for a
total of 1+7+NAMELEN=36 bytes. If the client does not care
which file system it attaches to, it can substitute the
string any for the name of the server. It calls encrypt(2)
to encrypt this string using the password typed by the user
at login time and stored in #c/key (KC). Next the client
prepares a Tauth message (see auth(5)): chal is set to the
Page 2 Plan 9 (printed 4/25/24)
AUTH(6) AUTH(6)
result of the encryption (KC{FScchal,ChC,S}) and uid to the
name of the user placing the call (C). This message is
transmitted to the server, S.
[2] The server prepares a string containing an initial byte
with value FSschal, another 7-byte random string (ChS), the
name of the client (C), and the contents of the chal field
of the 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 72+NAMELEN=100 bytes to the
authentication server.
The authentication server responds with one of two results,
both encrypted with the server's key. [3] If the authenti-
cation is approved, the (decrypted) result contains a byte
with value FSok, the server's challenge (ChS), and a
thirty-byte string, called chal, encrypted with the client's
key, to be returned to the client
(KC{FSctick,ChC,KT,KS{FSstick,ChS,KT}}). [4] If the authen-
tication is not approved, the result contains a byte with
value FSerr, the server challenge, and an error message.
[5] The server decrypts the response and sends either an
Rauth message with the chal field set to the chal string or
an 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.)
[6] If authentication succeeds, the client decrypts the chal
field of the Rauth and extracts the 15-byte long ticket
(KS{FSctick,ChS,KT}). It places that in the auth field of
the Tattach message it sends to establish the connection to
the server.
In the remaining protocol descriptions, the bytes transmit-
ted in the communications are exactly as presented in the
concise notation.
Rexauth
[1] S->C KS{RXschal, ChS}
[2] C->A KC{KS{RXschal, ChS}, S, RXcchal, ChC}, C
[3] A->C KC{KS{RXstick, ChS, C, KC}, RXctick, ChC}
[4] C->S KS{RXstick, ChS, C, KC}
[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 #c/chal and transmits it to C.
RXscal is a single byte identifying the message type.
[2] The client encapsulates the message in a larger message
containing the server name (S) , an RXcchal byte, a client
challenge (ChC), all encrypted, and the client name (C)
Page 3 Plan 9 (printed 4/25/24)
AUTH(6) AUTH(6)
(KC{KS{RXschal,ChS},S,RXcchal,ChC},C). This message is sent
to S which forwards it to the authentication server A.
[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.
[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 vali-
date further requests for the client from the server.
Chal
[1] S->A C, S, KS{RXschal, ChS}
[2] A->C NetCh
[3] C->A K'C{NetCh}
[4] A->S KS{RXstick, ChS, C, KC}
The chal protocol is closely related to 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 authenti-
cation server. The challenge and response are variable-
length NUL-terminated strings of digits. The rest of the
protocol is isomorphic to rexauth.
Changekey
[1] A->C ChA
[2] C->A C, KC{CKcchal, ChA, oPC, nPC}
[3] A->C password changed
or
[4] A->C E
This protocol is run directly between a user and the authen-
tication server to change the key for a user; no other
server is involved.
[1] The authentication server sends a challenge directly to
the client.
[2] The client constructs a message containing the name (C)
and an encrypted string holding a CKcchal byte, the chal-
lenge, the old password for the client (oPC) and the new
password (nPC). It returns this to the authentication
server.
[3] If the change is accepted the authentication server
returns the text string password changed.
[4] Otherwise, it returns an error string (E).
SEE ALSO
Page 4 Plan 9 (printed 4/25/24)
AUTH(6) AUTH(6)
auth(2), encrypt(2), intro(5), auth(5)
BUGS
The rexauth and chal protocols should create a new key for
the server to hold on behalf of the client.
Page 5 Plan 9 (printed 4/25/24)