AUTH(2)                                                   AUTH(2)

     NAME
          auth, amount, srvauth, authnonce, srvauthnonce,
          authenticate, getchal, chalreply, vncchal, vncreply,
          apopchal, apopreply, cramchal, cramreply,  newns, addns,
          authdial, passtokey, nvcsum, convT2M, convM2T, convTR2M,
          convM2TR, convA2M, convM2A, convPR2M, convM2PR, login,
          httpauth, noworld - network authentication

     SYNOPSIS
          #include <u.h>
          #include <libc.h>
          #include <auth.h>

          int  auth(int fd)

          int  srvauth(int fd, char *user)

          int  authnonce(int fd, uchar nonce[8])

          int  srvauthnonce(int fd, char *user, uchar nonce[8])

          int  getchal(Chalstate *c, char *user)

          int  chalreply(Chalstate *c, char *response)

          int  vncchal(VNCchalstate *c, char *user)

          int  vncreply(VNCchalstate *c, uchar *response)

          int  apopchal(Apopchalstate *c, char *user)

          int  apopreply(Apopchalstate *c, char *response)

          int  cramchal(Cramchalstate *c, char *user)

          int  cramreply(Cramchalstate *c, char *response)

          int  newns(char *user, char *nsfile)

          int  addns(char *user, char *nsfile)

          int  authdial(char *service)

          int  passtokey(char key[DESKEYLEN], char *password)

          uchar     nvcsum(void *mem, int len)

          int  authenticate(int fd, int afd)

          int  amount(int fd, char *old, int flag, char *aname)

     Page 1                       Plan 9             (printed 3/29/24)

     AUTH(2)                                                   AUTH(2)

          int  convT2M(Ticket *t, char *msg, char *key)

          void convM2T(char *msg, Ticket *t, char *key)

          int  convA2M(Authenticator *a, char *msg, char *key)

          void convM2A(char *msg, Authenticator *a, char *key)

          int  convTR2M(Ticketreq *tr, char *msg)

          void convM2TR(char *msg, Ticketreq *tr)

          int  convPR2M(Passwordreq *pr, char *msg, char *key)

          void convM2PR(char *msg, Passwordreq *pr, char *key)

          void login(char *user, char *password, char *namespace)

          int  httpauth(char *realm, char *password);

          int  noworld(char *user);

     DESCRIPTION
          These functions perform the authentication protocol as
          described in auth(6) for programs such as cpu(1), import(4),
          etc.

          Auth and srvauth authenticate connections for Plan 9 remote
          execution using the rexauth protocol described in auth(6).
          Auth is run by the caller and srvauth by the server; both
          return 0 if successful and -1 on error.  Fd is a file
          descriptor to the data channel.

          Srvauth authenticates the corresponding incoming call.  It
          copies the name of the user into user, which must be at
          least NAMELEN bytes long.

          Authnonce and srvauthnonce are versions of auth and srvauth
          that return an 8 byte nonce key.  The key is a DES key and
          hence has only 56 bits of random data, the other 8 being
          parity bits.

          Getchal and chalreply authenticate an incoming network call
          for a service that does not perform the usual Plan 9 authen-
          tication.  They use the chal protocol described in auth(6).
          User points to the local name of the user.  Getchal reads a
          null-terminated textual challenge from the authentication
          server and copies it to c->chal.  It returns 0 if it reaches
          the authentication server or -1 if it fails.  The challenge
          should be printed for the user to see, and the user should
          use a Digital Pathways SecureNet Key or netkey (see
          passwd(1)) to generate the appropriate response.

     Page 2                       Plan 9             (printed 3/29/24)

     AUTH(2)                                                   AUTH(2)

          Chalreply should be called with the user's response, which
          is also a null-terminated text string.  It returns 0 if it
          succeeds, or -1 if the user was not authenticated.

          Vncchal, vncreply, apopchal, apopreply, cramchal, and
          cramreply are similar to getchal and chalreply and are used
          much the same way.  The only differences are when the user
          name is known (before or after the challenge) and the format
          of the challenges and replies.  They negotiate the
          challenge/reply protocols for VNC, APOP (RFC1939), and CRAM
          (RFC2195) authentication.  They use the user's APOP secret
          which is different than his Plan 9 password or SecureNet
          Key.

          Srvauth, chalreply, vncreply, apopreply, and cramreply set
          the process's user name (see cons(3)).

          Vncchal and vncreply depend on changes currently being
          requested for the VNC authentication protocol.  Thus, they
          may be subject to change once the protocol is tied down.

          Newns builds a name space for user. It opens the file nsfile
          (/lib/namespace is used if nsfile is null), copies the old
          environment, and erases the current name space, sets the
          environment variables user and home, and interprets the com-
          mands in nsfile. The format of nsfile is described in
          namespace(6).

          Addns also interprets and executes the commands in nsfile.
          Unlike newns is applies the command to the current name
          space rather than starting from scratch.

          Authdial calls service on the local authentication server.
          It returns a file descriptor to the open connection or -1 if
          it fails.  Authdial is used to implement many of the other
          functions here; it is not normally called by users.

          Passtokey converts password into a DES key and stores the
          result in key. It returns 0 if password could not be con-
          verted, and 1 otherwise.

          Nvcsum computes a checksum for the len byte array mem. It is
          used to checksum keys stored in non-volatile RAM.

          Authenticate performs authentication to a file server at the
          other end of the channel referenced by fd. If afd is greater
          than or equal to zero and the authentication requires call-
          ing the authentication server then afd is used as a channel
          to it.  Otherwise, authenticate dials the authentication
          server using authdial().

          Amount is like mount but performs authentication on fd. It

     Page 3                       Plan 9             (printed 3/29/24)

     AUTH(2)                                                   AUTH(2)

          should be used instead of mount whenever the file server
          being mounted requires authentication.  See bind(2) for a
          definition of the arguments to mount and amount.

          ConvT2M, convA2M, convTR2M, and convPR2M convert tickets,
          authenticators, ticket requests, and password change request
          structures into transmittable messages.  ConvM2T, convM2A,
          convM2TR, and convM2PR are used to convert them back.  Key
          is used for encrypting the message before transmission and
          decrypting after reception.  These routines are used by the
          others to communicate with the authentication server.

          Login changes the the account the process is running as to
          user and recreates the namespace using the file namespace
          (default /lib/namespace).  It does this by negotiating with
          the authentication server using password to encrypt the
          exchange.

          Httpauth check a password for an HTTP page.  The realm iden-
          tifies the password to check for.  Like login, it does this
          by negotiating with the authentication server using password
          to encrypt the exchange.  Httpauth returns 0 on success and
          -1 on failure.

          Noworld returns 1 if the user is in the group noworld in
          /adm/users.  Otherwise, it returns 0.

     FILES
          /lib/namespace     Default name space specification file.

     SOURCE
          /sys/src/libauth

     SEE ALSO
          passwd(1), auth(6), cons(3), dial(2), auth(8)

     DIAGNOSTICS
          These routines set errstr. Integer-valued functions return
          -1 on error.

     Page 4                       Plan 9             (printed 3/29/24)