AUTH(3)                                                   AUTH(3)

     NAME
          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_userpasswd, auth_getuserpasswd,
          auth_getinfo, fsauth_proxy, fsfauth_proxy, fsamount,
          nsamount- routines for authenticating users

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

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

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

          AuthRpc*   auth_allocrpc(void);

          void           auth_freerpc(AuthRpc *rpc);

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

          int            auth_getkey(char *proto, char *dom);

          int            (*amount_getkey)(char*, char*);

          void           auth_freeAI(AuthInfo *ai);

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

          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, ...);

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

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

     AUTH(3)                                                   AUTH(3)

          AuthInfo*  auth_getinfo(AuthRpc *rpc);

          #include <9pclient.h>

          AuthInfo*  fsauth_proxy(CFid *fid, AuthGetkey *getkey, char
          *fmt, ...);

          AuthInfo*  fsfauth_proxy(CFid *fid, AuthRpc *rpc, AuthGetkey
          *getkey,
                         char *params);

          CFsys*     fsamount(int fd, char *aname);

          CFsys*     nsamount(char *name, char *aname);

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

          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 is meaningful only on Plan 9.  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 conversation.

          Auth_proxy proxies an authentication conversation between a
          remote server reading and writing fd and a factotum file, as
          opened by auth_allocrpc. An sprint (see print(3)) of fmt and
          the variable arg list yields a key template (see
          factotum(4)) specifying the key to use.  The template 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

     AUTH(3)                                                   AUTH(3)

          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. Auth_allocrpc arranges a connection to
          factotum, either by opening /mnt/factotum/rpc or by using
          9pclient(3) to connect to a factotum service posted in the
          current name space.  The returned connection 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 posess 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,
          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(3)                                                   AUTH(3)

          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_userpasswd verifies a simple user/password pair.
          Auth_getuserpasswd retrieves a user/password pair from
          factotum if permitted.

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

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

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

          Fsauth_proxy and fsfauth_proxy are like auth_proxy and
          fauth_proxy but execute the protocol on a CFid* (see
          9pclient(3)) instead of a file descriptor.

          Fsamount and nsamount are like fsmount and nsmount (see
          9pclient(3)) but use factotum to authenticate to the file
          servers.

     SOURCE
          /src/libauth

     SEE ALSO
          factotum(4), authsrv(3)

     DIAGNOSTICS
          These routines set errstr.