AUTHSRV(6) AUTHSRV(6)
NAME
authsrv, p9any, p9sk1, p9sk2 - authentication protocols
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, factotum(4) prompts for user name and
password. The user name becomes the terminal's authentica-
tion 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 possi-
ble, 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 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:
Ks server's host ID's key
Kc client's host ID's key
Kn a nonce key created for a ticket (key)
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)
Page 1 Plan 9 (printed 12/22/24)
AUTHSRV(6) AUTHSRV(6)
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 tick-
ets from the AS is the client's responsibility.
The protocol to obtain a ticket pair is:
A AuthTreq, IDs, DN, CHs, IDc, IDr
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 gener-
ates 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:
S CHc
The client starts by sending a random challenge to the
server.
C AuthTreq, IDs, DN, CHs, -, -
The server replies with a ticket request giving its id
Page 2 Plan 9 (printed 12/22/24)
AUTHSRV(6) AUTHSRV(6)
and authentication domain along with its own random
challenge.
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 inclu-
sion of CHs in the authenticator avoids replay
attacks.)
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 authenti-
cate 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:
C v.2 proto@authdom proto@authdom ...
S proto dom
C OK
Each message is a NUL-terminated UTF string. The server
begins by sending a list of proto, authdom pairs it is will-
ing 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 ser-
vices. 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
Page 3 Plan 9 (printed 12/22/24)
AUTHSRV(6) AUTHSRV(6)
Users connect directly to the AS to change their passwords.
The protocol is:
A AuthPass, IDc, DN, CHc, IDc, IDc
The client sends a password change ticket request.
C Kc{AuthTp, CHc, IDc, IDc, Kn}
The server responds with a ticket containing the key Kn
encrypted with the client's key Kc
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.
C AuthOK or AuthErr, 64-byte error message
The AS responds with simply AuthOK or with AuthErr fol-
lowed 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 authten-
ticating. 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 send-
ing an AuthOK message containing a server ticket and authen-
ticator.
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
Page 4 Plan 9 (printed 12/22/24)
AUTHSRV(6) AUTHSRV(6)
of the data that follows.
Anywhere an AuthOK message is expected, a AuthErr message
may be substituted.
A AuthChal, IDs, DN, CHs, IDs, IDc
S AuthOK, challenge
A response
S AuthOK, Ks{AuthChal, IDs, DN, CHs, IDs, IDc, Kn},
Kn{AuthTs, CHs}
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.
A AuthApop , IDs, DN, CHs, -, -
S AuthOKvar, challenge
A AuthApop , IDs, DN, CHs, IDc, IDc; hexadecimal MD5
checksum
S AuthOK, Ks{AuthApop, IDs, DN, CHs, IDs, IDc, Kn},
Kn{AuthTs, CHs}
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
Page 5 Plan 9 (printed 12/22/24)
AUTHSRV(6) AUTHSRV(6)
authentication server sends back a ticket and authenti-
cator. 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)).
A AuthChap, IDs, DN, CHs, -, -
S challenge
A pktid, IDc, response
S AuthOK, Ks{AuthChap, IDs, DN, CHs, IDs, IDc, Kn},
Kn{AuthTs, CHs}
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>.
A AuthMSchap, IDs, DN, CHs, -, -
S challenge
A IDc, lm-response, nt-response
S AuthOK, Ks{AuthMschap, IDs, DN, CHs, IDs, IDc, Kn},
Kn{AuthTs, CHs}
This protocol implements Microsoft's MS-CHAP authenti-
cation (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>.
A AuthVNC, IDs, DN, CHs, IDs, IDc
S AuthOKvar, challenge
A response
S AuthOK, Ks{, IDs, DN, CHs, IDs, IDc, Kn}, Kn{AuthTs,
CHs}
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.
FILES
/lib/ndb/auth database file
/lib/ndb/auth.* hash files for /lib/ndb/auth
Page 6 Plan 9 (printed 12/22/24)
AUTHSRV(6) AUTHSRV(6)
SEE ALSO
auth(2), fauth(2), cons(3), attach(5), auth(8)
Page 7 Plan 9 (printed 12/22/24)