glenda.party
term% ls -F
term% cat index.txt
AUTH(2)                       System Calls Manual                      AUTH(2)



NAME
       amount,   newns,   addns,   login,  noworld,  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 -  rou‐
       tines 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);

       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 *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  *getkey,  char  *fmt,
       ...);

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

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

       AuthInfo*  auth_getinfo(int fd);

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 environment 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 user and recreates the names‐
       pace 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  pro‐
       vide sandboxed access for some users.

       The following routines use the AuthInfo structure returned after a suc‐
       cessful 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
       conversation.

       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 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 authentications.  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 facto‐
       tum  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.  Individ‐
       ual 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 specified 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 specify‐
       ing  a  key,  and  it  will  use factotum to return the proper user and
       response.

       Auth_userpasswd verifies a simple  user/password  pair.   Auth_getuser‐
       passwd retrieves a user/password pair from factotum if permitted:

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

       Auth_getinfo  reads  an AuthInfo message from fd 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.



                                                                       AUTH(2)