man(1) Manual page archive

     AUTH(6)                                                   AUTH(6)

          fsauth, rexauth, chal, changekey - authentication services

          This manual page describes the authentication services: the
          protocols used to authorize connections, confirm the identi-
          ties of users and machines, and maintain the associated
          databases.  The machine that provides these services is
          called the authentication server and may be a stand-alone
          machine or a general-use machine such as a CPU server.  The
          network database holds for each public machine, such as a
          CPU server or file server, the name of the authentication
          server that machine uses.

          There are four authentication services.  Each is executed by
          making a network call from the machine wishing authentica-
          tion to the authentication server and exchanging messages.
          The services are:

          fsauth   authenticate file system attaches
          rexauth  authenticate remote execution from a Plan 9 machine
          chal     authenticate connections from a non-Plan 9 machine
                   using a SecureNet box (see securenet(8))
                   change the key for a user or client.
          Multiple fsauth requests may be processed on a single con-
          nection to the authentication server.  The other protocols
          accept only one request per call.
          When a client calls another machine, say a file server,
          using the 9P protocol, the file server receives a Tauth mes-
          sage containing information about the user making the call
          (see auth(5)). The file server exchanges some messages with
          the authentication server using the fsauth protocol
          described below.  It then returns an Rauth message to the
          client containing a ticket to be used by the client in the
          subsequent Tattach message (see attach(5)); that ticket
          guarantees that the user requesting the service is the one
          validated by authentication server.
          In describing the protocols, the following notation is used.
          A    The authentication server.
          S    A CPU server or file server.
          C    A client connecting to S.  When any of these appears as
               part of a message, it refers to the textual name of the
               agent padded with zeros to a total of NAMELEN bytes.
          Kx   The seven byte authentication key of x; x is either S
               or C.  Servers keep a private copy of their keys, typi-
               cally in non-volatile RAM, and encrypt using the
               library functions encrypt(2) and decrypt. Clients keep
               a copy of the current user's key in the file #c/key and
               encrypt using the file #c/crypt (see cons(3)).

     AUTH(6)                                                   AUTH(6)

          K'C  C's network key, stored in C's SecureNet box.  Encryp-
               tion with K'C is done with the algorithm described in
               securenet(8). KC may also be used in place of K'C to
               execute the chal protocol without a SecureNet box; in
               this case, the netcrypt routine is used for encryption.
               In either case the result of the encryption is a vari-
               able length text string, to be transmitted with its
               terminating NUL.
          KT   A ticket key, a random number stored in a ticket.
            A password for the client: a 10 byte NUL-terminated
               string.  The character x is either o for an old pass-
               word or n for a new one.
          Chx  A seven byte challenge made by x; x is one of A, S, or
               A NUL-terminated string of between 1 and 6 digits for
               encryption using K'C.  NetCh is a challenge generated
               by A and is transmitted as a variable length NUL-
               terminated string.
               Braces denote encryption.  Kx{s} is the result of
               encrypting s using key Kx.
          E    An error message ERRLEN bytes long.

          Arrows indicate communication.  The authentication server
          communicates only with a server, so a communication between
          A and C indicates that S forwards the message uninterpreted.

          Consider the fsauth protocol to validate a connection to a
          file server.  Here is the concise notation of the protocol;
          following that is a prose description of its execution:

          [1] C→S  KC{FScchal, ChC, S}, C
          [2] S→A  KS{FSschal, ChS, C, KC{FScchal, ChC, S}}, S
          [3] A→S  KS{FSok, ChS, KC{FSctick, ChC, KT, KS{FSstick, ChS,
          [4] A→S  KS{FSerr, ChS, E}
          [5] S→C  KC{FSctick, ChC, KT, KS{FSstick, ChS, KT}}
          [6] C→S  KS{FSstick, ChS, KT}

          [1] The client prepares a string containing an initial byte
          with value FScchal (defined in <auth.h>), a seven-byte ran-
          dom string, ChC, and the name of the server it is calling,
          e.g.  kremvax, padded with zeros to NAMELEN bytes, for a
          total of 1+7+NAMELEN=36 bytes.  If the client does not care
          which file system it attaches to, it can substitute the
          string any for the name of the server.  It calls encrypt(2)
          to encrypt this string using the password typed by the user
          at login time and stored in #c/key (KC).  Next the client
          prepares a Tauth message (see auth(5)): chal is set to the

     AUTH(6)                                                   AUTH(6)

          result of the encryption (KC{FScchal,ChC,S}) and uid to the
          name of the user placing the call (C).  This message is
          transmitted to the server, S.

          [2] The server prepares a string containing an initial byte
          with value FSschal, another 7-byte random string (ChS), the
          name of the client (C), and the contents of the chal field
          of the Tauth message.  It encrypts this using the server's
          key (KS) and appends its own name to the 2*36=72 resulting
          bytes and sends the total 72+NAMELEN=100 bytes to the
          authentication server.

          The authentication server responds with one of two results,
          both encrypted with the server's key.  [3] If the authenti-
          cation is approved, the (decrypted) result contains a byte
          with value FSok, the server's challenge (ChS), and a
          thirty-byte string, called chal, encrypted with the client's
          key, to be returned to the client
          (KC{FSctick,ChC,KT,KS{FSstick,ChS,KT}}).  [4] If the authen-
          tication is not approved, the result contains a byte with
          value FSerr, the server challenge, and an error message.

          [5] The server decrypts the response and sends either an
          Rauth message with the chal field set to the chal string or
          an Rerror message containing the error describing why
          authentication failed.  (The error case is not shown in the
          concise form; it is outside the authentication protocol.)

          [6] If authentication succeeds, the client decrypts the chal
          field of the Rauth and extracts the 15-byte long ticket
          (KS{FSctick,ChS,KT}).  It places that in the auth field of
          the Tattach message it sends to establish the connection to
          the server.

          In the remaining protocol descriptions, the bytes transmit-
          ted in the communications are exactly as presented in the
          concise notation.

          [1] S→C  KS{RXschal, ChS}
          [2] C→A  KC{KS{RXschal, ChS}, S, RXcchal, ChC}, C
          [3] A→C  KC{KS{RXstick, ChS, C, KC}, RXctick, ChC}
          [4] C→S  KS{RXstick, ChS, C, KC}

          [1] The client C calls the (CPU) server, which recognizes
          the incoming call and reads the already-encrypted string
          KS{RXschal,ChS} from the file #c/chal and transmits it to C.
          RXscal is a single byte identifying the message type.

          [2] The client encapsulates the message in a larger message
          containing the server name (S) , an RXcchal byte, a client
          challenge (ChC), all encrypted, and the client name (C)

     AUTH(6)                                                   AUTH(6)

          (KC{KS{RXschal,ChS},S,RXcchal,ChC},C).  This message is sent
          to S which forwards it to the authentication server A.

          [3] The authentication server forms a new message
          (KC{KS{RXstick,ChS,C,KC},RXctick,ChC}) and sends it through
          the server to the client.

          [4] The client decrypts this message and extracts a ticket
          (KS{RXstick,ChS,C,KC}) which it sends to the server.  The
          ticket contains the client key (KC) so the server may vali-
          date further requests for the client from the server.

          [1] S→A  C, S, KS{RXschal, ChS}
          [2] A→C  NetCh
          [3] C→A  K'C{NetCh}
          [4] A→S  KS{RXstick, ChS, C, KC}

          The chal protocol is closely related to rexauth. The main
          difference [2] is that the authentication server sends to
          the client a challenge (NetCh) to be encrypted by a
          SecureNet box.  The result is returned [3] to the authenti-
          cation server.  The challenge and response are variable-
          length NUL-terminated strings of digits.  The rest of the
          protocol is isomorphic to rexauth.

          [1] A→C  ChA
          [2] C→A  C, KC{CKcchal, ChA, oPC, nPC}
          [3] A→C  password changed
          [4] A→C  E

          This protocol is run directly between a user and the authen-
          tication server to change the key for a user; no other
          server is involved.

          [1] The authentication server sends a challenge directly to
          the client.

          [2] The client constructs a message containing the name (C)
          and an encrypted string holding a CKcchal byte, the chal-
          lenge, the old password for the client (oPC) and the new
          password (nPC).  It returns this to the authentication

          [3] If the change is accepted the authentication server
          returns the text string password changed.

          [4] Otherwise, it returns an error string (E).


     AUTH(6)                                                   AUTH(6)

          auth(2), encrypt(2), intro(5), auth(5)

          The rexauth and chal protocols should create a new key for
          the server to hold on behalf of the client.