term% cat index.txt AUTH(6) Games Manual AUTH(6)
delim $$ define lbr ' roman "{" ' define rbr ' roman "}" '
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 associ‐
ated 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 authentication; a
56-bit DES key, a 28-byte authentication ID, and a 48-byte authentica‐
tion domain name. The ID is a user name and identifies who is cur‐
rently 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 authentication 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 bootp(8). For Datakit machines the AS is a system called p9auth
on the same Datakit node as the file server the terminal booted from.
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 semantics 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:
$CH sub c$
an 8-byte random challenge from a client
$CH sub s$
an 8-byte random challenge from a server
$K sub s$
server's key
$K sub c$
client's key
$K sub n$
a nonce key created for a ticket
$K lbr m rbr$
message $m$ encrypted with key $K$
$ID sub s$
server's ID
$DN sub s$
server's authentication domain name
$ID sub c$
client's ID
$UID sub c$
user's name on the client
$UID sub s$
user's name on the server
A number of constants defined in auth.h are also used: AuthTreq, Au‐
thChal, 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 different 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 authentication: the server, the client kernel, the user process on
the client, and the authentication server. The goal of the authentica‐
tion 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 infor‐
mation is exchanged once at the beginning of the session within a ses‐
sion message (see attach(5)):
ClientâServer
Tsession($CH sub c$)
ServerâClient
Rsession(${CH sub s},~{ID sub s},~{DN sub s}$)
Each time a user mounts a file server connection, an attach message is
sent identifying/authenticating the user:
ClientâServer
Tattach($K sub s lbr AuthTs, ~ {CH sub s},~{UID sub c}, ~ {UID
sub s}, ~ K sub n rbr , ~ {K sub n} lbr AuthAc, ~ {CH sub s},
count rbr )$
ServerâClient
Rattach($ K sub n lbr AuthAs,~{CH sub c},~count rbr$)
The part of the attach request encrypted with $Ksubs$ 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 $K sub n$ found in the ticket is called an authenticator. The au‐
thenticator 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 process. The AS
contains a database of which $ID sub c$'s may speak for which $UID sub
c$'s. If the $ID sub c$ may speak for the $UID sub c$, two tickets are
returned.
UserProcâAS
$AuthTreq, ~ CH sub s , ~ ID sub s , ~ DN sub s , ~ ID sub c , ~
UID sub c$
ASâUserProc
$AuthOK, ~ K sub c lbr AuthTc, ~ CH sub s , ~ UID sub c , ~
UID sub s , ~ K sub n rbr , ~ K sub s lbr AuthTs, ~ CH sub
s , ~ UID sub c , ~ UID sub s , ~ K sub n rbr$
Otherwise an error message is returned.
ASâ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 en‐
crypted with $K sub c$. If $UID sub c$ matches the user's login ID,
the tickets are remembered for any subsequent attaches by that user of
that file server session. Otherwise, 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.
ServerâUserProc
$AuthTreq, ~ CH sub s , ~ ID sub s , ~ DN sub s , ~ xxx, ~
xxx$
Here xxx indicates a field whose contents do not matter.
The calling process adds its machine's $ID sub c$ and its $UID sub c$
to the request and follows the protocol outlined above to get two tick‐
ets from the AS. The process passes the $K sub s$ encrypted ticket
plus an authenticator generated by /dev/authenticator from the $K sub
c$ 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 authentica‐
tor which can be written to the kernel along with the $K sub c$ en‐
crypted ticket to confirm the server's identity (see cons(3)).
UserProcâServer
$ K sub s lbr AuthTs, ~ CH sub s , ~ UID sub c , ~ UID sub s
, ~ K sub n rbr , ~ K sub n lbr AuthAc, ~ CH sub s , ~ 0
rbr $
ServerâUserProc
$K sub n lbr AuthAs, ~ CH sub s , ~ 0 rbr$
Challenge Box
A user may also start a process on a CPU server from a non Plan 9 ma‐
chine 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 authentication server. If the AS has keys for both the
$ID sub c$ and $UID sub c$ in the ticket request it returns a challenge
as a hexadecimal number.
DaemonâAS
$AuthChal, ~ CH sub c , ~ ID sub c , ~ DN sub s , ~ ID sub c
, ~ UID sub c $
ASâDaemon
$AuthOK$, 16-byte ASCII challenge
Otherwise, it returns a null-terminated 64-byte error string.
ASâDaemon
$AuthErr$, 64-byte error string
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.
DaemonâAS
16-byte ASCII response
ASâDaemon
$AuthOK, ~ K sub c lbr AuthTs, ~ CH sub c , ~ UID sub c , ~
UID sub c , ~ K sub n rbr$
or
ASâ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 en‐
crypts both the old and new keys with the $K sub n$ from the returned
ticket and sends that back to the AS. The AS checks the reply for va‐
lidity and replies with an AuthOK byte or an error message.
UserProcâAS
$AuthPass, ~ xxx, ~ xxx, ~ xxx, ~ xxx, ~ UID sub c$
ASâUserProc
$AuthOK, ~ K sub c lbr AuthTc, ~ xxx, ~ xxx, ~ xxx, ~ K sub
n rbr$
UserProcâAS
$K sub u lbr AuthPass, ~ roman "old password", ~ roman "new
password" rbr$
ASâUserProc
$AuthOK$
or
ASâUserProc
$AuthErr$, 64-byte error string
Data Base
An ndb(2) database file exists for the authentication server. The at‐
tribute 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
SEE ALSO
fsession(2), auth(2), cons(3), attach(5), auth(8)
AUTH(6)