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 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.
When a terminal boots,
factotum(4)
prompts for user name and password.
The user name becomes the terminal's authentication ID.
The password is converted using
passtokey
(see
authsrv(2))
into a 56-bit DES key and saved in memory.
The authentication domain is set to the null string.
If possible,
factotum
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,
factotum
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:
- Ks
- server's host ID's key
- Kc
- client's host ID's key
- Kn
- a nonce key created for a ticket
(key)
- K{m}
- message
m
encrypted with key
K
- CHc
- an 8-byte random challenge from a client
(chal)
- CHs
- an 8-byte random challenge from a server
(chal)
- IDs
- server's ID
(authid)
- DN
- server's authentication domain name
(authdom)
- IDc
- client's ID
(hostid,
cuid)
- IDr
- client's desired ID on server
(uid,
suid)
The parenthesized names are the ones used in the
Ticketreq
and
Ticket
structures in
<authsrv.h>.
The message type constants
AuthTreq,
AuthChal,
AuthPass,
AuthOK,
AuthErr,
AuthMod,
AuthApop,
AuthOKvar,
AuthChap,
AuthMSchap,
AuthCram,
and
AuthVNC
(type)
are defined in
<authsrv.h>,
as are the encrypted message types
AuthTs,
AuthAs,
AuthAc,
AuthTp,
and
AuthHr
(num).
- Ticket Service
-
When a client and server wish to authenticate to each other,
they do so using
tickets
issued by the AS.
Obtaining tickets from the AS
is the client's responsibility.
The protocol to obtain a ticket pair is:
- C->A
- AuthTreq,
IDs,
DN,
CHs,
IDc,
IDr
- A->C
- AuthOK,
Kc{AuthTc,
CHs,
IDc,
IDr,
Kn},
Ks{AuthTs,
CHs,
IDc,
IDr,
Kn}
The two tickets are identical except for their type fields
and the keys with which they are encrypted.
The client and server can each decrypt one of the tickets,
establishing a shared secret
Kn.
The
tickets can be viewed as a statement by the
AS that
``a client possessing the
Kn
key is allowed to authenticate as
IDr.''
The presence of the server challenge
CHs
in the ticket allows the server to verify the freshness
of the ticket pair.
The AS sets the
IDr
in the tickets to the requested
IDr
only if
IDc
is allowed to
speak for
(q.v.)
IDr.
If not,
the AS sets
IDr
to the empty string.
If the users
IDc
or
IDs
do not exist,
the AS silently generates one-time
random keys to use in place of
Kc
or
Ks,
so that clients cannot probe the AS
to learn whether a user name is valid.
- P9sk1
-
The Plan 9 shared key protocol
p9sk1
allows a client and server to authenticate each other.
The protocol is:
- C->S
- CHc
The client starts by sending a random challenge to the server.
- S->C
- AuthTreq,
IDs,
DN,
CHs,
-,
-
The server replies with a ticket request giving its
id and authentication domain along with its own
random challenge.
- C->S
- Ks{AuthTs,
CHs,
IDc,
IDr,
Kn},
Kn{AuthAc,
CHs}
The client adds
IDc
and
IDr
to the ticket request and obtains a ticket pair
from the AS as described above.
The client relays the server's ticket along with
an
authenticator,
the
AuthAc
message.
The authenticator proves to the server that the
client knows
Kn
and is therefore allowed to authenticate as
IDr.
(The inclusion of
CHs
in the authenticator avoids replay attacks.)
- S->C
- Kn{AuthAs,
CHc}
The server replies with its own authenticator,
proving to the client that it also knows
Kn
and therefore
Ks .
P9sk2
is an older variant of
p9sk1
used only when connecting to pre-9P2000 remote
execution services.
It omits the first message and last
messages and therefore does not
authenticate the server to the client.
- P9any
-
P9any
is the standard Plan 9 authentication protocol.
It consists of a negotiation to determine a common
protocol, followed by the agreed-upon protocol.
The negotiation protocol is:
- S->C
- v.2
proto@authdom
proto@authdom
...
- C->S
- proto
dom
- S->C
- OK
Each message is a NUL-terminated UTF string.
The server begins by sending a list of
proto,
authdom
pairs it is willing to use.
The client
responds with its choice.
Requiring the client to wait for the final
OK
ensures that the client will not start
the chosen protocol until the server is ready.
The above is version 2 of the protocol.
Version 1,
no longer used,
omitted the first message's
v.2
prefix
and the
OK
message.
The
p9any
protocol is the protocol used by all
Plan 9 services.
The file server runs it over special
authentication files
(see
fauth(2)
and
attach(5)).
Other services, such as
cpu(1)
and
exportfs(4),
run
p9any
over the network and then
use
Kn
to derive an
ssl(3)
key to encrypt the rest of their communications.
- Password Change
-
Users connect directly to the AS
to change their passwords.
The protocol is:
- C->A
- AuthPass,
IDc,
DN,
CHc,
IDc,
IDc
The client sends a password change ticket request.
- A->C
- Kc{AuthTp,
CHc,
IDc,
IDc,
Kn}
The server responds with a ticket containing the key
Kn
encrypted with the client's key
Kc
- C->A
- Kn{AuthPass,
old,
new,
changesecret,
secret}
The client decrypts the ticket using the old password
and then sends back an encrypted password request
(Passwordreq
structure)
containing the old password and the new password.
If
changesecret
is set, the AS also changes
the user's
secret,
the password used for non-Plan 9 authentications.
- A->C
- AuthOK
or
AuthErr,
64-byte error message
The AS responds with simply
AuthOK
or with
AuthErr
followed by a 64-byte error message.
- Authentication Database
-
An
ndb(2)
database file
/lib/ndb/auth
exists for the AS.
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
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.
This property is used heavily on CPU servers.
- Foreign Protocols
-
The AS accepts ticket request
messages of types other than
AuthTreq
to allow users to
authenticate using non-Plan 9 protocols.
In these situations, the server communicates
directly with the AS.
Some protocols must begin without knowing the
client's name. They ignore the client name in the
ticket request.
All the protocols end
with the AS sending
an
AuthOK
message containing a server ticket and authenticator.
AuthOK
messages
always have a fixed but context-dependent size.
The occasional variable-length OK message starts with a
AuthOKvar
byte and a five-byte space-padded decimal length of the
data that follows.
Anywhere an
AuthOK
message is expected, a
AuthErr
message may be substituted.
- A->S
- AuthOK,
Ks{\$1,
IDs,
DN,
CHs,
IDs,
IDc,
Kn},
Kn{AuthTs,
CHs}
- S->A
- AuthChal,
IDs,
DN,
CHs,
IDs,
IDc
- A->S
- AuthOK,
challenge
- S->A
- response
- This protocol allows the use of
handheld authenticators such as SecureNet
keys and SecureID tokens
in programs such as
ssh(1)
and
ftpd
(see
ipserv(8)).
- Challenge
and
response
are text strings,
NUL -padded
to 16 bytes
(NETCHLEN).
The
challenge
is a random five-digit decimal number.
When using a SecureNet key or
netkey
(see
passwd(1)),
the
response
is an eight-digit decimal or hexadecimal number
that is an encryption of the challenge
using the user's DES key.
- When using a SecureID token,
the challenge is ignored.
The response is the user's PIN followed by
the six-digit number currently displayed
on the token.
In this case, the AS
queries an external RADIUS server
to check the response.
Use of a RADIUS server requires an entry in
the authentication database. For example:
radius=server-name secret=xyzzy
uid=howard rid=trickey
uid=sape rid=smullender
- In this example, the secret
xyzzy
is the hash key used in talking to the RADIUS server.
The
uid/rid
lines map from Plan 9 user ids to RADIUS ids.
Users not listed are assumed to have the
same id in both places.
- S->A
- AuthApop ,
IDs,
DN,
CHs,
-,
-
- A->S
- AuthOKvar,
challenge
- S->A
- AuthApop ,
IDs,
DN,
CHs,
IDc,
IDc;
hexadecimal MD5 checksum
- This protocol implements APOP authentication
(see
pop3(8)).
After receiving a ticket request of type
AuthApop,
the AS generates a random challenge
of the form
<random@domain>.
The client then replies with a new ticket request
giving the user name
followed by the MD5 checksum of
the challenge concatenated with the user's secret.
If the response is correct, the authentication
server sends back a ticket
and authenticator.
If the response is incorrect, the client may repeat the
ticket request/MD5 checksum message to try again.
- The
AuthCram
protocol runs identically to the
AuthApop
protocol, except that the expected MD5 checksum
is the keyed MD5 hash using the user's secret as the key
(see
hmac_md5
in
sechash(2)).
- S->A
- AuthChap,
IDs,
DN,
CHs,
-,
-
- A->S
- challenge
- S->A
- pktid,
IDc,
response
- This protocol implements CHAP authentication
(see
ppp(8)).
The
challenge
is eight random bytes.
The response is a 16-byte MD5 checksum
over the packet id, user's secret, and challenge.
The reply packet is defined as
OChapreply
in
<authsrv.h>.
- S->A
- AuthMSchap,
IDs,
DN,
CHs,
-,
-
- A->S
- challenge
- S->A
- IDc,
lm-response,
nt-response
- This protocol implements Microsoft's MS-CHAP
authentication
(see
ppp(8)).
The
challenge
is eight random bytes.
The two responses are Microsofts LM and NT hashes.
Only the NT hash may be used to authenticate,
as the LM hash is considered too weak.
The reply packet is defined as
OMSchapreply
in
<authsrv.h>.
- S->A
- AuthVNC,
IDs,
DN,
CHs,
IDs,
IDc
- A->S
- AuthOKvar,
challenge
- S->A
- response
- This protocol implements VNC authentication
(see
vncs
in
vnc(1)).
The challenge is 16 random bytes, and the response
is a DES ECB encryption of the challenge.
The method by which VNC converts the user's
secret into a DES key is weak,
considering only the first eight bytes of the secret.