ref: 67edb3bd015c635216f9cd3eaffaf16c228c790f
dir: /sys/man/2/auth/
.TH AUTH 2 .SH 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_respondAI, 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 .B int newns(char *user, char *nsfile); .PP .B int addns(char *user, char *nsfile); .PP .B int amount(int fd, char *old, int flag, char *aname); .PP .B int login(char *user, char *password, char *namespace); .PP .B int noworld(char *user); .PP .B AuthInfo* auth_proxy(int fd, AuthGetkey *getkey, char *fmt, ...); .PP .B AuthInfo* fauth_proxy(int fd, AuthRpc *rpc, AuthGetkey *getkey, .br .B char *params); .PP .B AuthRpc* auth_allocrpc(int afd); .PP .B void auth_freerpc(AuthRpc *rpc); .PP .B uint auth_rpc(AuthRpc *rpc, char *verb, void *a, int n); .PP .B int auth_getkey(char *params); .PP .B int (*amount_getkey)(char*); .PP .B void auth_freeAI(AuthInfo *ai); .PP .B int auth_chuid(AuthInfo *ai, char *ns); .PP .B Chalstate* auth_challenge(char *fmt, ...); .PP .B AuthInfo* auth_response(Chalstate*); .PP .B void auth_freechal(Chalstate*); .PP .B int auth_respond(void *chal, uint nchal, char *user, uint nuser, void *resp, uint nresp, AuthGetkey *getkey, char *fmt, ...); .PP .B int auth_respondAI(void *chal, uint nchal, char *user, uint nuser, void *resp, uint nresp, AuthInfo **ai, AuthGetkey *getkey, char *fmt, ...); .PP .B AuthInfo* auth_userpasswd(char*user, char*password); .PP .B UserPasswd* auth_getuserpasswd(AuthGetkey *getkey, char*fmt, ...); .PP .B AuthInfo* auth_getinfo(AuthRpc*); .SH DESCRIPTION .PP This library, in concert with .IR factotum (4), is used to authenticate users. It provides the primary interface to .IR factotum . .PP .I Newns builds a name space for .IR user . It opens the file .I nsfile .RB ( /lib/namespace is used if .I nsfile is null), copies the old environment, erases the current name space, sets the environment variables .B user and .BR home , and interprets the commands in .IR nsfile . The format of .I nsfile is described in .IR namespace (6). .PP .I Addns also interprets and executes the commands in .IR nsfile . Unlike .I newns it applies the command to the current name space rather than starting from scratch. .PP .I Amount is like .I mount but performs any authentication required. It should be used instead of .I mount whenever the file server being mounted requires authentication. See .IR bind (2) for a definition of the arguments to .I mount and .IR amount . .PP .I Login changes the user id of the process .I user and recreates the namespace using the file .I namespace (default .BR /lib/namespace ). It uses .I auth_userpasswd and .IR auth_chuid . .PP .I Noworld returns 1 if the user is in the group .B noworld in .BR /adm/users . Otherwise, it returns 0. .I Noworld is used by telnetd and ftpd to provide sandboxed access for some users. .PP The following routines use the .B AuthInfo structure returned after a successful authentication by .IR factotum (4). .IP .ne 8 .EX .ta 4n +4n +4n +4n +4n +4n +4n +4n +4n typedef struct { char *cuid; /* caller id */ char *suid; /* server id */ char *cap; /* capability */ int nsecret; /* length of secret */ uchar *secret; /* secret */ } AuthInfo; .EE .PP The fields .B cuid and .B suid point to the authenticated ids of the client and server. .B Cap is 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 Secret is an .BR 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. .PP .I Auth_proxy proxies an authentication conversation between a remote server reading and writing .I fd and a .I factotum file. The .I factotum file used is .BR /mnt/factotum/rpc . An .B sprint (see .IR print (2)) of .I fmt and 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=client or .BR role=server ). .I Auth_proxy either returns an allocated .B AuthInfo structure, or sets the error string and returns nil. .PP .I Fauth_proxy can be used instead of .I auth_proxy if a single connection to .I factotum will be used for multiple authentications. This is necessary, for example, for .I newns which must open the .I factotum file before wiping out the namespace. .I Fauth_proxy takes as an argument a pointer to an .B AuthRPC structure which contains an fd for an open connection to .I factotum in addition to storage and state information for the protocol. An .B AuthRPC structure is obtained by calling .I auth_allocrpc with the fd of an open .I factotum connection. It is freed using .IR auth_freerpc . Individual commands can be sent to .IR factotum (4) by invoking .IR auth_rpc . .PP Both .I auth_proxy and .I fauth_proxy take a pointer to a routine, .IR getkey , to invoke should .I factotum not posess a key for the authentication. If .I getkey is nil, the authentication fails. .I Getkey is called with a key template for the desired key. We have provided a generic routine, .IR auth_getkey , which queries the user for the 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_chuid uses the .B cuid and .B cap fields of an .B AuthInfo structure to change the user id of the current process and uses .IR ns , default .BR /lib/namespace , to build it a new name space. .PP .I Auth_challenge and .I auth_response perform challenge/response protocols with .IR factotum . State between the challenge and response phase are kept in the .B Chalstate structure: .IP .EX 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; }; .EE .PP .I Auth_challenge requires a key template generated by an .B sprint of .I fmt and 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 P9cr and .B vnc expect the user specified as an attribute in the key template and .BR apop , .BR cram , and .BR chap expect it in the .B user field of the arg to .IR auth_response . For all protocols, the response is returned to .I auth_response in the .I resp field of the .BR Chalstate . .I Chalstate.nresp must be the length of the response. .PP Supply to .I auth_respond a challenge string and the fmt and args specifying a key, and it will use .I factotum to return the proper user and response. .PP .I Auth_respondAI is like .I auth_respond but has an additional .I ai output parameter to return an .I AuthInfo structure on success that holds protocol specific secret keys derived from the exchange. The returned .I AuthInfo structure should be freed with .I auth_freeAI by the caller. .PP .I Auth_userpasswd verifies a simple user/password pair. .I Auth_getuserpasswd retrieves a user/password pair from .I factotum if permitted: .IP .ne 8 .EX .ta 4n +4n +4n +4n +4n +4n +4n +4n +4n typedef struct UserPasswd { char *user; char *passwd; } UserPasswd; .EE .PP .I Auth_getinfo reads an .B AuthInfo message from .I rpc and converts it into a structure. It is only used by the other routines in this library when communicating with .IR factotum . .PP .I Auth_freeAI is used to free an .B AuthInfo structure returned by one of these routines. Similary .I auth_freechal frees a challenge/response state. .SH SOURCE .B /sys/src/libauth .SH SEE ALSO .IR factotum (4), .IR authsrv (2), .IR bind (2) .SH DIAGNOSTICS These routines set .IR errstr .