   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 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->AAuthTreq, IDs, DN, CHs, IDc, IDr
   A->CAuthOK, 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->CAuthTreq, IDs, DN, CHs, –, –
   The server replies with a ticket request giving its id and
   authentication domain along with its own random challenge.
   C->SKs{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->CKn{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->AAuthPass, IDc, DN, CHc, IDc, IDc
   The client sends a password change ticket request.
   A->CKc{AuthTp, CHc, IDc, IDc, Kn}
   The server responds with a ticket containing the key Kn encrypted with
   the client's key Kc
   C->AKn{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.

   S->AAuthChal, IDs, DN, CHs, IDs, IDc
   A->SAuthOK, challenge
   S->Aresponse
   A->SAuthOK, 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.
   S->A   AuthApop , IDs, DN, CHs, –, –
   A->SAuthOKvar, challenge
   S->A   AuthApop , IDs, DN, CHs, IDc, IDc; hexadecimal MD5 checksum
   A->SAuthOK, 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 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->AAuthChap, IDs, DN, CHs, –, –
   A->S   challenge
   S->Apktid, IDc, response
   A->SAuthOK, 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>.
   S->AAuthMSchap, IDs, DN, CHs, –, –
   A->S   challenge
   S->AIDc, lm–response, nt–response
   A->SAuthOK, Ks{AuthMschap, IDs, DN, CHs, IDs, IDc, Kn}, Kn{AuthTs, CHs}
   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->AAuthVNC, IDs, DN, CHs, IDs, IDc
   A->SAuthOKvar, challenge
   S->A   response
   A->SAuthOK, 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

   SEE ALSO

   auth(2), fauth(2), cons(3), attach(5), auth(8)

   Copyright © 2026 Alcatel-Lucent. All rights reserved.
