.TH AUTHSRV 6
.SH NAME
ticket \- authentication service
.SH 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
.I authentication server
(AS).
The AS may be a stand-alone machine or a general-use machine such as a CPU server.
The network database
.IR ndb (6)
holds for each public machine, such as a CPU server or
file server, the name of the authentication server that machine uses.
.PP
Each machine contains three values important to authentication; 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.
.PP
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
.I passtokey
(see
.IR 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
.IR dhcpd (8).
.PP
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.
.PP
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:
.TF nullx
.TP
.I \fICHc\fP
an 8-byte random challenge from a client
.TP
.I CHs
an 8-byte random challenge from a server
.TP
.I \fIKs\fP
server's key
.TP
.I \fIKc\fP
client's key
.TP
.I \fIKn\fP
a nonce key created for a ticket
.TP
.I K\fP\fIm\fP
message m
encrypted with key K
.TP
.I \fIIDs\fP
server's ID
.TP
.I \fIDNs\fP
server's authentication domain name
.TP
.I \fIIDc\fP
client's ID
.TP
.I \fIUIDc\fP
user's name on the client
.TP
.I \fIUIDs\fP
user's name on the server
.PD
.PP
A number of constants defined in
.B auth.h
are also used:
.IR AuthTreq,
.IR AuthChal,
.IR AuthOK,
.IR AuthErr,
.IR AuthTs,
.IR AuthTc,
.IR AuthAs,
and
.IR AuthAc .
.SS "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
.I mounts
a file server
(see
.IR 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 authentication protocol is to convince the server
that the client may validly speak for the user process.
.PP
To reduce the number of messages for each authentication,
common information is exchanged once at the
beginning of the session within a
.I session
message
(see
.IR attach (5)):
.TF "Client->Server"
.TP
.IR Client -> Server
Tsession( \fICHc\fP )
.TP
.IR Server -> Client
Rsession( \fICHs\fP, \fIIDs\fP, \fIDNs\fP )
.PD
.PP
Each time a user mounts a file server connection, an attach
message is sent identifying/authenticating the user:
.TF "Client->Server"
.TP
.IR Client -> Server
Tattach( \fIKs\fP{ \fIAuthTs\fP, \fICHs\fP, \fIUIDc\fP, \fIUIDs\fP, \fIKn\fP }, \fIKn\fP{ \fIAuthAc\fP, \fICHs\fP, \fIcount\fP } )
.TP
.IR Server -> Client
Rattach( \fIKn\fP{ AuthAs, \fICHc\fP, \fIcount\fP } )
.PD
.PP
The part of the attach request encrypted with
.BR \fIKs\fP
is called a
.IR 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
.B \fIKn\fP
found in the ticket is called an
.IR authenticator .
The authenticator is generated by the client kernel and guarantees that
the ticket was not stolen.
The
.I 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.
.PP
Tickets are created by the AS at the request of a user process.
The AS contains a database of which \fIIDc\fP's may speak for which \fIUIDc\fP's.
If the \fIIDc\fP may speak for the \fIUIDc\fP, two tickets are returned.
.TF "UserProc->AS"
.TP
.IR UserProc -> AS
\fIAuthTreq\fP, \fICHs\fP, \fIIDs\fP, \fIDNs\fP, \fIIDc\fP, \fIUIDc\fP
.TP
.IR AS -> UserProc
\fIAuthOK\fP, \fIKc\fP{ \fIAuthTc\fP, \fICHs\fP, \fIUIDc\fP, \fIUIDs\fP, \fIKn\fP }, \fIKs\fP{ \fIAuthTs\fP, \fICHs\fP, \fIUIDc\fP, \fIUIDs\fP, \fIKn\fP }
.PD
.PP
Otherwise an error message is returned.
.TF "UserProc->AS"
.TP
.IR AS -> UserProc
\fIAuthErr\fP, 64-byte error string
.PD
.PP
The user passes both tickets to the client's kernel using
the
.I fauth
system call
(see
.IR fauth (2)).
The kernel decrypts the ticket encrypted with \fIKc\fP.
If \fIUIDc\fP
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.
.SS "Remote Execution"
.PP
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
.IR cpu (1),
.I rx
(see
.IR con (1)),
and
.IR exportfs (4).
The called process replies to the connection with a ticket request.
.TF "Server->UserProc"
.TP
.IR Server -> UserProc
\fIAuthTreq\fP, \fICHs\fP, \fIIDs\fP, \fIDNs\fP, xxx, xxx
.PD
.PP
Here
.I xxx
indicates a field whose contents do not matter.
.PP
The calling process adds its machine's \fIIDc\fP and its \fIUIDc\fP to the request
and follows the protocol outlined above to get two tickets from the AS.
The process passes the
\fIKs\fP
encrypted ticket plus an authenticator generated by
.B /dev/authenticator
from the 
\fIKc\fP
ticket to the remote server, which writes them to the
kernel to set the user ID (see 
.IR cons (3)).
The server replies with its own authenticator which can be written
to the kernel along with the
\fIKc\fP
encrypted ticket to confirm the server's identity (see
.IR cons (3)).
.TF "UserProc->Server"
.TP
.IR UserProc -> Server
\fIKs\fP{ \fIAuthTs\fP, \fICHs\fP, \fIUIDc\fP, \fIUIDs\fP, \fIKn\fP }, \fIKn\fP{ \fIAuthAc\fP, \fICHs\fP, 0 } 
.TP
.IR Server -> UserProc
\fIKn\fP{ \fIAuthAs\fP, \fICHs\fP, 0 }
.PD
.SS "Challenge Box"
A user may also start a process on a CPU server from a non Plan 9
machine using commands such as
.IR con,
.IR telnet,
or
.I ftp
(see
.IR con (1)
and
.IR 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 \fIIDc\fP and \fIUIDc\fP in the ticket
request it returns a challenge as a hexadecimal number.
.TF "Daemon->AS"
.TP
.IR Daemon -> AS
\fIAuthChal\fP, \fICHc\fP, \fIIDc\fP, \fIDNs\fP, \fIIDc\fP, \fIUIDc\fP 
.TP
.IR AS -> Daemon
\fIAuthOK\fP, 16-byte
.SM ASCII
challenge
.PD
.PP
Otherwise, it returns a null-terminated 64-byte error string.
.TF "Daemon->AS"
.TP
.IR AS -> Daemon
\fIAuthErr\fP, 64-byte error string
.PD
.PP
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.
.TF "Daemon->AS"
.TP
.IR Daemon -> AS
16-byte
.SM ASCII
response
.TP
.IR AS -> Daemon
\fIAuthOK\fP, \fIKc\fP{ \fIAuthTs\fP, \fICHc\fP, \fIUIDc\fP, \fIUIDc\fP, \fIKn\fP }
.PD
.PP
or
.TF "Daemon->AS"
.TP
.IR AS -> Daemon
\fIAuthErr\fP, 64-byte error string
.PD
.PP
Finally, the daemon passes the ticket to the kernel
to set the user ID (see
.IR cons (3)).
.SS "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
\fIKn\fP from the returned ticket and sends that back to the AS.
The AS checks the reply for validity and replies with an
\fIAuthOK\fP byte or an error message.
.TF "UserProc->AS"
.TP
.IR UserProc -> AS
\fIAuthPass\fP, xxx, xxx, xxx, xxx, \fIUIDc\fP
.TP
.IR AS -> UserProc
\fIAuthOK\fP, \fIKc\fP{ \fIAuthTp\fR, xxx, xxx, xxx, \fIKn\fP }
.TP
.IR UserProc -> AS
\fIKn\fP{ \fIAuthPass\fP, "old password", "new password" }
.TP
.IR AS -> UserProc
\fIAuthOK\fP
.PD
.PP
or
.TF "UserProc->AS"
.TP
.IR AS -> UserProc
\fIAuthErr\fP, 64-byte error string
.PD
.PP
.SS "Data Base"
An
.IR ndb (2)
database file exists for the authentication server.
This database maintains ``speaks for'' relationships, i.e.,
it lists which users may speak for other users when
authtenticating.
The attribute types used by the AS are
.B hostid
and
.BR uid .
The value in the
.B hostid
is a client host's ID.
The values in the
.B uid
pairs in the same entry list which users that host ID
make speak for.
A uid value of
.B *
means the host ID may speak for all users.
A uid value of
.BI ! user
means the host ID may not speak for
.IR user .
For example:
.PP
.EX
hostid=bootes
	uid=!sys uid=!adm uid=*
.EE
.PP
is interpreted as
.B bootes
may speak for any user except
.B sys
and
.BR adm .
This property is used heavily on cpu servers.
.PP
The
.I ndb
database is also used when talking to Lucent Radius
servers to check SecureID authentications.  The database
file provides the Radius server's secret key and
to mappings from local uid's to those known by the server.
The attribute type
.B radius
identifies the Radius server.
The attribute
.B secret
provides the hash key used in talking to the
server.
The attributes
.B uid
and 
.B rid
profile the local and remote user id's when verifying
a SecureID login.
For example:
.PP
.EX
radius=lra-radius secret=xyzzy
	uid=bob		rid=roberttheworkstation
.EE
.PP
says that when verifying SecureID's on server
.BR lra-radius ,
use the hash key
.BR xyzzy .
Local user
.B bob
is known as
.B roberttheworkstation
on the radius server.
.SH FILES
.TF /lib/ndb/auth.*xxx
.TP
.B /lib/ndb/auth
database file
.TP
.B /lib/ndb/auth.*
hash files for
.B /lib/ndb/auth
.SH SEE ALSO
.IR auth (2),
.IR fauth (2),
.IR cons (3),
.IR attach (5),
.IR auth (8)