glenda.party
term% ls -F
term% cat index.txt
AUTHSRV(6)                       Games Manual                       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  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, 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  op‐
       erator 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,  Au‐
       thErr,  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 pos‐
       sessing 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  au‐
       thenticate 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 au‐
              thentication 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 mes‐
              sage.   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 un‐
       til 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 proto‐
       col 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 en‐
              crypted 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  changese‐
              cret 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 authenticating.  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 may 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 situ‐
       ations,  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  sub‐
       stituted.

       S→A    AuthChal, IDs, DN, CHs, IDs, IDc
       A→S    AuthOK, challenge
       S→A    response
       A→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 num‐
              ber.  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  re‐
              sponse  is  the user's PIN followed by the six-digit number cur‐
              rently 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 talk‐
              ing 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
       A→S    AuthOK, Ks{AuthApop, IDs, DN, CHs,  IDs,  IDc,  Kn},  Kn{AuthTs,
              CHs}

              This protocol implements APOP authentication (see pop3(8)).  Af‐
              ter receiving a ticket request of type AuthApop, the  AS  gener‐
              ates a random challenge of the form <random@domain>.  The client
              then replies with a new ticket request giving the user name fol‐
              lowed 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  us‐
              ing 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
       A→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>.

       S→A    AuthMSchap, IDs, DN, CHs, -, -
       A→S    challenge
       S→A    IDc, lm-response, nt-response
       A→S    AuthOK,  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 re‐
              sponses are Microsoft's 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
       A→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

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



                                                                    AUTHSRV(6)