|  | 
 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,
 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 *getkey, char *fmt, ...); 
    
    
    AuthInfo* auth_userpasswd(char*user, char*password); 
    
    
    UserPasswd* auth_getuserpasswd(AuthGetkey *getkey, char*fmt, ...);
    
    
    
    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,
 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 {
 
 } AuthInfo;|  |  |  | char    *cuid;      /* caller id */ char    *suid;      /* server id */
 char    *cap;          /* capability */
 int nsecret;       /* length of secret */
 uchar *secret;       /* secret */
 
 | 
 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 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
    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
 {
 
 /* for implementation only */|  |  |  | char    *user; char    chal[MAXCHLEN];
 int nchal;
 void    *resp;
 int nresp;
 
 | 
 
 };|  |  |  | 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
    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 {
 
 } UserPasswd;|  |  |  | char    *user; char    *passwd;
 
 | 
 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     
 SEE ALSO    
 DIAGNOSTICS     
 |  |  |  | These routines set errstr. 
 | 
 |  |