From cfa37a7b1131abbab2e7d339b451f5f0e3198cc8 Mon Sep 17 00:00:00 2001 From: rsc Date: Sat, 10 Apr 2004 18:53:55 +0000 Subject: Lots of man pages. --- man/man3/auth.3 | 395 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 395 insertions(+) create mode 100644 man/man3/auth.3 (limited to 'man/man3/auth.3') diff --git a/man/man3/auth.3 b/man/man3/auth.3 new file mode 100644 index 00000000..cec79ce7 --- /dev/null +++ b/man/man3/auth.3 @@ -0,0 +1,395 @@ +.TH AUTH 3 +.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_userpasswd, auth_getuserpasswd, auth_getinfo\- routines for authenticating users +.SH SYNOPSIS +.nf +.PP +.ft L +#include +#include +#include +.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 *proto, char *dom); +.PP +.B +int (*amount_getkey)(char*, 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 +AuthInfo* auth_userpasswd(char*user, char*password); +.PP +.B +UserPasswd* auth_getuserpasswd(AuthGetkey *getkey, char*fmt, ...); +.PP +.B +AuthInfo* auth_getinfo(int fd); +.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/nnamespace ). +It uses +.I auth_userpassword +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). +.PP +.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 +.sp +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: +.sp +.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 +.sp +.I Auth_challenge +requires a key template generated by an +.B sprint +of +.I fmt +and the variable arguments. It must contain the protocol +(\fBproto=\fIxxx\fR) +and depending on the protocol, the user name ( +.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_userpasswd +verifies a simple user/password pair. +.I Auth_getuserpasswd +retrieves a user/password pair from +.I factotum +if permitted. +.PP +.I Auth_getinfo +reads an +.B AuthInfo +message from +.I fd +and converts it into a structure. It is only +used by the other routines in this library when +communicating with +.IR factotum . +.PP +.ne 8 +.EX +.ta 4n +4n +4n +4n +4n +4n +4n +4n +4n +typedef struct UserPasswd { + char *user; + char *passwd; +} UserPasswd; +.EE +.sp +.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 . -- cgit v1.2.3