AUTH(2)                                                   AUTH(2)

     NAME
          amount, newns, addns, login, noworld, procsetuser,
          auth_proxy, fauth_proxy, auth_allocrpc, auth_freerpc,
          auth_rpc, auth_getkey, amount_getkey, auth_freeAI,
          auth_chuid, auth_challenge, auth_response, auth_freechal,
          auth_respond, auth_respondAI, auth_userpasswd,
          auth_getuserpasswd, auth_getinfo - routines for
          authenticating users

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

          int            newns(char *user, char *nsfile);

          int            addns(char *user, char *nsfile);

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

          int            login(char *user, char *password, char
          *namespace);

          int            noworld(char *user);

          int            procsetuser(char *user);

          AuthInfo*  auth_proxy(int fd, AuthGetkey *getkey, char *fmt,
          ...);

          AuthInfo*  fauth_proxy(int fd, AuthRpc *rpc, AuthGetkey
          *getkey,
                         char *params);

          AuthRpc*   auth_allocrpc(int afd);

          void           auth_freerpc(AuthRpc *rpc);

          uint           auth_rpc(AuthRpc *rpc, char *verb, void *a,
          int n);

          int            auth_getkey(char *params);

          int            (*amount_getkey)(char*);

          void           auth_freeAI(AuthInfo *ai);

          int                auth_chuid(AuthInfo *ai, char *ns);

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

     AUTH(2)                                                   AUTH(2)

          Chalstate* auth_challenge(char *fmt, ...);

          AuthInfo*  auth_response(Chalstate*);

          void           auth_freechal(Chalstate*);

          int                auth_respond(void *chal, uint nchal, char
          *user, uint nuser, void *resp, uint nresp, AuthGetkey *get-
          key, char *fmt, ...);

          int                auth_respondAI(void *chal, uint nchal,
          char *user, uint nuser, void *resp, uint nresp, AuthInfo
          **ai, AuthGetkey *getkey, char *fmt, ...);

          AuthInfo*  auth_userpasswd(char*user, char*password);

          UserPasswd*    auth_getuserpasswd(AuthGetkey *getkey,
          char*fmt, ...);

          AuthInfo*  auth_getinfo(AuthRpc*);

     DESCRIPTION
          This library, in concert with factotum(4), is used to
          authenticate users.  It provides the primary interface to
          factotum.

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

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

          Amount is like mount but performs any authentication
          required.  It 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.

          Login changes the user id of the process to user and recre-
          ates the namespace using the file namespace (default
          /lib/namespace).  It uses auth_userpasswd and auth_chuid.

          Noworld returns 1 if the user is in the group noworld in
          /adm/users.  Otherwise, it returns 0.  Noworld is used by
          telnetd and ftpd to provide sandboxed access for some users.

          Procsetuser changes the user id of the process to user but

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

     AUTH(2)                                                   AUTH(2)

          keeps the namespace unchanged.  Only hostowner can change
          the user to anything other than the none user.

          The following routines use the AuthInfo structure returned
          after a successful authentication by factotum(4).

               typedef struct
               {
                   char    *cuid;      /* caller id */
                   char    *suid;      /* server id */
                   char    *cap;           /* capability */
                   int nsecret;        /* length of secret */
                   uchar   *secret;        /* secret */
               } AuthInfo;

          The fields cuid and suid point to the authenticated ids of
          the client and server.  Cap is a capability returned only to
          the server.  It can be passed to the cap(3) device to change
          the user id of the process.  Secret is an nsecret-byte
          shared secret that can be used by the client and server to
          create encryption and hashing keys for the rest of the con-
          versation.

          Auth_proxy proxies an authentication conversation between a
          remote server reading and writing fd and a factotum file.
          The factotum file used is /mnt/factotum/rpc.  An sprint (see
          print(2)) of fmt and the variable arg list yields a key tem-
          plate (see factotum(4)) specifying the key to use.  The tem-
          plate must specify at least the protocol ( proto=xxx) and
          the role (either role=client or role=server).  Auth_proxy
          either returns an allocated AuthInfo structure, or sets the
          error string and returns nil.

          Fauth_proxy can be used instead of auth_proxy if a single
          connection to factotum will be used for multiple authentica-
          tions.  This is necessary, for example, for newns which must
          open the factotum file before wiping out the namespace.
          Fauth_proxy takes as an argument a pointer to an AuthRPC
          structure which contains an fd for an open connection to
          factotum in addition to storage and state information for
          the protocol.  An AuthRPC structure is obtained by calling
          auth_allocrpc with the fd of an open factotum connection.
          It is freed using auth_freerpc. Individual commands can be
          sent to factotum(4) by invoking auth_rpc.

          Both auth_proxy and fauth_proxy take a pointer to a routine,
          getkey, to invoke should factotum not possess a key for the
          authentication.  If getkey is nil, the authentication fails.
          Getkey is called with a key template for the desired key.
          We have provided a generic routine, auth_getkey, which
          queries the user for the key information and passes it to
          factotum. This is the default for the global variable,

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

     AUTH(2)                                                   AUTH(2)

          amount_getkey, which holds a pointer to the key prompting
          routine used by amount.

          Auth_chuid uses the cuid and cap fields of an AuthInfo
          structure to change the user id of the current process and
          uses ns, default /lib/namespace, to build it a new name
          space.

          Auth_challenge and auth_response perform challenge/response
          protocols with factotum. State between the challenge and
          response phase are kept in the Chalstate structure:

               struct Chalstate
               {
                   char    *user;
                   char    chal[MAXCHLEN];
                   int nchal;
                   void    *resp;
                   int nresp;

               /* for implementation only */
                   int afd;
                   AuthRpc *rpc;
                   char    userbuf[MAXNAMELEN];
                   int userinchal;
               };

          Auth_challenge requires a key template generated by an
          sprint of fmt and the variable arguments.  It must contain
          the protocol (proto=xxx) and depending on the protocol, the
          user name (user=xxx).  P9cr and vnc expect the user speci-
          fied as an attribute in the key template and apop, cram, and
          chap expect it in the user field of the arg to
          auth_response. For all protocols, the response is returned
          to auth_response in the resp field of the Chalstate.
          Chalstate.nresp must be the length of the response.

          Supply to auth_respond a challenge string and the fmt and
          args specifying a key, and it will use factotum to return
          the proper user and response.

          Auth_respondAI is like auth_respond but has an additional ai
          output parameter to return an AuthInfo structure on success
          that holds protocol specific secret keys derived from the
          exchange. The returned AuthInfo structure should be freed
          with auth_freeAI by the caller.

          Auth_userpasswd verifies a simple user/password pair.
          Auth_getuserpasswd retrieves a user/password pair from
          factotum if permitted:

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

     AUTH(2)                                                   AUTH(2)

               typedef struct UserPasswd {
                   char    *user;
                   char    *passwd;
               } UserPasswd;

          Auth_getinfo reads an AuthInfo message from rpc and converts
          it into a structure.  It is only used by the other routines
          in this library when communicating with factotum.

          Auth_freeAI is used to free an AuthInfo structure returned
          by one of these routines.  Similary auth_freechal frees a
          challenge/response state.

     SOURCE
          /sys/src/libauth

     SEE ALSO
          factotum(4), authsrv(2), bind(2)

     DIAGNOSTICS
          These routines set errstr.

     Page 5                       Plan 9             (printed 3/28/24)