FreeBSD Manual Pages
AUTH(3) Library Functions Manual 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_ge- tuserpasswd, 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 *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, 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 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 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 re- turns an allocated AuthInfo structure, or sets the error string and re- turns 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. 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 in- voking 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 re- sponse. Auth_userpasswd verifies a simple user/password pair. Auth_getuser- passwd 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 li- brary 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. AUTH(3)
NAME | SYNOPSIS | DESCRIPTION | SOURCE | SEE ALSO | DIAGNOSTICS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=auth&sektion=3&manpath=FreeBSD+Ports+15.0.quarterly>