AUTH(6) AUTH(6)
NAME
ticket - authentication service
DESCRIPTION
This manual page describes 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 authentication server
(AS). The AS may be a stand-alone machine or a general-use
machine such as a CPU server. The network database ndb(6)
holds for each public machine, such as a CPU server or file
server, the name of the authentication server that machine
uses.
Each machine contains three values important to authentica-
tion; a 56-bit DES key, a 28-byte authentication ID, and a
48-byte authentication domain name. The ID is a user name
and identifies who is currently responsible for the kernel
running on that machine. The domain name identifies the
machines across which the ID is valid. Together, the ID and
domain name identify the owner of a key.
When a terminal boots, the user is prompted for user name
and password. The user name becomes the terminal's authen-
tication ID. The password is converted using passtokey (see
auth(2)) into a 56-bit DES key and saved as the machine's
key. The authentication domain is set to the null string.
If possible, the terminal validates the key with the AS
before saving it. For Internet machines the correct AS to
ask is found using dhcpd(8).
When a CPU or file server boots, it reads the key, ID, and
domain name from non-volatile RAM. This allows servers to
reboot without operator intervention.
The details of any authentication are mixed with the seman-
tics of the particular service they are authenticating so we
describe them one case at a time. The following definitions
will be used in the descriptions:
CHc an 8-byte random challenge from a client
CHs an 8-byte random challenge from a server
Ks server's key
Kc client's key
Kn a nonce key created for a ticket
Km message m encrypted with key K
IDs server's ID
DNs server's authentication domain name
IDc client's ID
UIDc user's name on the client
Page 1 Plan 9 (printed 4/30/24)
AUTH(6) AUTH(6)
UIDs user's name on the server
A number of constants defined in auth.h are also used:
AuthTreq, AuthChal, AuthOK, AuthErr, AuthTs, AuthTc, AuthAs,
and AuthAc.
File Service
File service sessions are long-lived connections between a
client host and a file server. Processes belonging to dif-
ferent users share the session. Whenever a user process on
the client mounts a file server (see bind(2)), it must
authenticate itself. There are four players in an authenti-
cation: the server, the client kernel, the user process on
the client, and the authentication server. The goal of the
authentication protocol is to convince the server that the
client may validly speak for the user process.
To reduce the number of messages for each authentication,
common information is exchanged once at the beginning of the
session within a session message (see attach(5)):
Server Tsession( CHc )
Client Rsession( CHs, IDs, DNs )
Each time a user mounts a file server connection, an attach
message is sent identifying/authenticating the user:
Server Tattach( Ks{ AuthTs, CHs, UIDc, UIDs, Kn },
Kn{ AuthAc, CHs, count } )
Client Rattach( Kn{ AuthAs, CHc, count } )
The part of the attach request encrypted with Ks is called a
ticket. Since it is encrypted in the server's secret key,
this message is guaranteed to have originated on the AS.
The part encrypted with the Kn found in the ticket is called
an authenticator. The authenticator is generated by the
client kernel and guarantees that the ticket was not stolen.
The count is incremented with each mount to make every
authenticator unique, thus foiling replay attacks. The
server is itself authenticated by the authenticator it sends
as a reply to the attach.
Tickets are created by the AS at the request of a user pro-
cess. The AS contains a database of which IDc's may speak
for which UIDc's. If the IDc may speak for the UIDc, two
tickets are returned.
AS AuthTreq, CHs, IDs, DNs, IDc, UIDc
UserProc AuthOK, Kc{ AuthTc, CHs, UIDc, UIDs, Kn }, Ks{
AuthTs, CHs, UIDc, UIDs, Kn }
Otherwise an error message is returned.
Page 2 Plan 9 (printed 4/30/24)
AUTH(6) AUTH(6)
UserProc AuthErr, 64-byte error string
The user passes both tickets to the client's kernel using
the fauth system call (see fsession(2)). The kernel decrypts
the ticket encrypted with Kc. If UIDc matches the user's
login ID, the tickets are remembered for any subsequent
attaches by that user of that file server session. Other-
wise, the ticket is assumed stolen and an error is returned.
Remote Execution
A number of applications require a process on one machine to
start a process with the same user ID on a server machine.
Examples are cpu(1), rx (see con(1)), and exportfs(4). The
called process replies to the connection with a ticket
request.
UserProc AuthTreq, CHs, IDs, DNs, xxx, xxx
Here xxx indicates a field whose contents do not matter.
The calling process adds its machine's IDc and its UIDc to
the request and follows the protocol outlined above to get
two tickets from the AS. The process passes the Ks
encrypted ticket plus an authenticator generated by
/dev/authenticator from the Kc ticket to the remote server,
which writes them to the kernel to set the user ID (see
cons(3)). The server replies with its own authenticator
which can be written to the kernel along with the Kc
encrypted ticket to confirm the server's identity (see
cons(3)).
Server Ks{ AuthTs, CHs, UIDc, UIDs, Kn }, Kn{
AuthAc, CHs, 0 }
UserProc Kn{ AuthAs, CHs, 0 }
Challenge Box
A user may also start a process on a CPU server from a non
Plan 9 machine using commands such as con, telnet, or ftp
(see con(1) and ftpfs(4)). In these situations, the user can
authenticate using a hand-held DES encryptor. The telnet or
FTP daemon first sends a ticket request to the authentica-
tion server. If the AS has keys for both the IDc and UIDc
in the ticket request it returns a challenge as a hexadeci-
mal number.
AS AuthChal, CHc, IDc, DNs, IDc, UIDc
Daemon AuthOK, 16-byte ASCII challenge
Otherwise, it returns a null-terminated 64-byte error
string.
Daemon AuthErr, 64-byte error string
Page 3 Plan 9 (printed 4/30/24)
AUTH(6) AUTH(6)
The daemon relays the challenge to the calling program,
which displays the challenge on the user's screen. The user
encrypts it and types in the result, which is relayed back
to the AS. The AS checks it against the expected response
and returns either a ticket or an error.
AS 16-byte ASCII response
Daemon AuthOK, Kc{ AuthTs, CHc, UIDc, UIDc, Kn }
or
Daemon AuthErr, 64-byte error string
Finally, the daemon passes the ticket to the kernel to set
the user ID (see cons(3)).
Password Change
Any user can change the key stored for him or her on the AS.
Once again we start by passing a ticket request to the AS.
Only the user ID in the request is meaningful. The AS
replies with a single ticket (or an error message) encrypted
in the user's personal key. The user encrypts both the old
and new keys with the Kn from the returned ticket and sends
that back to the AS. The AS checks the reply for validity
and replies with an AuthOK byte or an error message.
AS AuthPass, xxx, xxx, xxx, xxx, UIDc
UserProc AuthOK, Kc{ AuthTp, xxx, xxx, xxx, Kn }
AS Kn{ AuthPass, "old password", "new password" }
UserProc AuthOK
or
UserProc AuthErr, 64-byte error string
Data Base
An ndb(2) database file exists for the authentication
server. The attribute types used by the AS are hostid and
uid. The value in the hostid is a client host's ID. The
values in the uid pairs in the same entry list which users
that host ID make speak for. A uid value of * means the
host ID may speak for all users. A uid value of !user means
the host ID may not speak for user. For example:
hostid=bootes
uid=!sys uid=!adm uid=*
is interpreted as bootes may speak for any user except sys
and adm.
FILES
/lib/ndb/auth database file
/lib/ndb/auth.* hash files for /lib/ndb/auth
Page 4 Plan 9 (printed 4/30/24)
AUTH(6) AUTH(6)
SEE ALSO
fsession(2), auth(2), cons(3), attach(5), auth(8)
Page 5 Plan 9 (printed 4/30/24)