.TH AUTH 2.SH NAMEamount, 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 \- routines for authenticating users.SH SYNOPSIS.nf.PP.ft L#include <u.h>#include <libc.h>#include <auth.h>.fi.ta 11n +4n +4n +4n +4n +4n +4n.PP.Bint		newns(char *user, char *nsfile);.PP.Bint		addns(char *user, char *nsfile);.PP.Bint		amount(int fd, char *old, int flag, char *aname);.PP.Bint		login(char *user, char *password, char *namespace);.PP.Bint		noworld(char *user);.PP.BAuthInfo*	auth_proxy(int fd, AuthGetkey *getkey, char *fmt, ...);.PP.BAuthInfo*	fauth_proxy(int fd, AuthRpc *rpc, AuthGetkey *getkey,.br.B			char *params);.PP.BAuthRpc*	auth_allocrpc(int afd);.PP.Bvoid		auth_freerpc(AuthRpc *rpc);.PP.Buint		auth_rpc(AuthRpc *rpc, char *verb, void *a, int n);.PP.Bint		auth_getkey(char *proto, char *dom);.PP.Bint		(*amount_getkey)(char*, char*);.PP.Bvoid		auth_freeAI(AuthInfo *ai);.PP.Bint			auth_chuid(AuthInfo *ai, char *ns);.PP.BChalstate*	auth_challenge(char *fmt, ...);.PP.BAuthInfo*	auth_response(Chalstate*);.PP.Bvoid		auth_freechal(Chalstate*);.PP.Bint			auth_respond(void *chal, uint nchal, char *user, uint nuser, void *resp, uint nresp, AuthGetkey *getkey, char *fmt, ...);.PP.BAuthInfo*	auth_userpasswd(char*user, char*password);.PP.BUserPasswd*	auth_getuserpasswd(AuthGetkey *getkey, char*fmt, ...);.PP.BAuthInfo*	auth_getinfo(int fd);.SH DESCRIPTION.PPThis library, in concert with.IR factotum (4),is used to authenticate users.It provides the primary interface to.IR factotum ..PP.I Newnsbuilds a name space for.IR user .It opens the file.I nsfile.RB ( /lib/namespaceis used if.I nsfileis null),copies the old environment, erases the current name space,sets the environment variables.B userand.BR home ,and interprets the commands in.IR nsfile .The format of.I nsfileis described in.IR namespace (6)..PP.I Addnsalso interprets and executes the commands in.IR nsfile .Unlike.I newnsit applies the command to the current name spacerather than starting from scratch..PP.I Amountis like.I mountbut performs any authentication required.It should be used instead of.I mountwhenever the file server being mounted requires authentication.See.IR bind (2)for a definition of the arguments to.I mountand.IR amount ..PP.I Loginchanges the user id of the process.I userand recreates the namespace using the file.I namespace(default.BR /lib/namespace ).It uses.I auth_userpasswdand.IR auth_chuid ..PP.I Noworldreturns 1 if the user is in the group.B noworldin.BR /adm/users .Otherwise, it returns 0..I Noworldis used by telnetd and ftpd to provide sandboxedaccess for some users..PPThe following routines use the.B AuthInfostructure returned after a successful authentication by.IR factotum (4)..IP.ne 8.EX.ta 4n +4n +4n +4n +4n +4n +4n +4n +4ntypedef struct{	char	*cuid;		/* caller id */	char	*suid;		/* server id */	char	*cap;			/* capability */	int	nsecret;		/* length of secret */	uchar	*secret;		/* secret */} AuthInfo;.EE.PPThe fields.B cuidand.B suidpoint to the authenticated ids of the client and server..B Capis a capability returned only to the server.It can be passed to the.IR cap (3)device to change the user id of the process..B Secretis an.BR nsecret -byteshared secret that can be used by the client and server tocreate encryption and hashing keys for the rest of theconversation..PP.I Auth_proxyproxies an authentication conversation between a remoteserver reading and writing.I fdand a.I factotumfile.  The.I factotumfile used is.BR /mnt/factotum/rpc .An.B sprint(see.IR print (2))of .I fmtand the variable arg list yields a key template (see.IR factotum (4))specifying the key to use.The template must specify at least the protocol (.BI proto= xxx )and the role (either.B role=clientor.BR role=server )..I Auth_proxyeither returns an allocated.B AuthInfostructure, or sets the error string andreturns nil..PP.I Fauth_proxycan be used instead of.I auth_proxyif a single connection to.I factotumwill be used for multiple authentications.This is necessary, for example, for.I newnswhich must open the.I factotumfile before wiping out the namespace..I Fauth_proxytakes as an argument a pointer to an.B AuthRPCstructure which contains an fd for an open connection to.I factotumin addition to storage and state information forthe protocol.An.B AuthRPCstructure is obtained by calling.I auth_allocrpcwith the fd of an open.I factotumconnection.It is freed using.IR auth_freerpc .Individual commands can be sent to.IR factotum (4)by invoking.IR auth_rpc ..PPBoth.I auth_proxyand.I fauth_proxytake a pointer to a routine,.IR getkey ,to invoke should.I factotumnot posess a key for the authentication.  If.I getkeyis nil, the authentication fails..I Getkeyis called with a key template for the desiredkey.We have provided a generic routine,.IR auth_getkey ,which queries the user forthe key information and passes it to.IR factotum .This is the default for the global variable,.IR amount_getkey ,which holds a pointer to the key prompting routine used by.IR amount ..PP.I Auth_chuiduses the.B cuidand.B capfields of an.B AuthInfostructure to change the user id of the currentprocess and uses.IR ns ,default.BR /lib/namespace ,to build it a new name space..PP.I Auth_challengeand.I auth_responseperform challenge/response protocols with.IR factotum .State between the challenge and response phase arekept in the.B Chalstatestructure:.IP.EXstruct Chalstate{	char	*user;	char	chal[MAXCHLEN];	int	nchal;	void	*resp;	int	nresp; /* for implementation only */	int	afd;	AuthRpc	*rpc;	char	userbuf[MAXNAMELEN];	int	userinchal;};.EE.PP.I Auth_challengerequires a key template generated by an.B sprintof.I fmtand the variable arguments.  It must contain the protocol(\fLproto=\fIxxx\fR)and depending on the protocol, the user name (\c.BI user= xxx \fR).\fP.B P9crand.B vncexpect the user specified as an attribute inthe key template and.BR apop ,.BR cram ,and.BR chapexpect it in the .B userfield of the arg to.IR auth_response .For all protocols, the response is returnedto.I auth_responsein the.I respfield of the.BR Chalstate ..I Chalstate.nrespmust be the length of the response..PPSupply to.I auth_responda challenge string and the fmt and args specifying a key,and it will use.I factotumto return the proper user and response..PP.I Auth_userpasswdverifies a simple user/password pair..I Auth_getuserpasswdretrieves a user/password pair from.I factotumif permitted:.IP.ne 8.EX.ta 4n +4n +4n +4n +4n +4n +4n +4n +4ntypedef struct UserPasswd {	char	*user;	char	*passwd;} UserPasswd;.EE.PP.I Auth_getinforeads an.B AuthInfomessage from.I fdand converts it into a structure.  It is onlyused by the other routines in this library whencommunicating with.IR factotum ..PP.I Auth_freeAIis used to free an.B AuthInfostructure returned by one of these routines.Similary.I auth_freechalfrees a challenge/response state..SH SOURCE.B /sys/src/libauth.SH SEE ALSO.IR factotum (4),.IR authsrv (2),.IR bind (2).SH DIAGNOSTICSThese routines set.IR errstr .