From d93fca6a7ab52f518d3e8aca1fc94139313b97ad Mon Sep 17 00:00:00 2001 From: rsc Date: Fri, 11 Feb 2005 19:21:47 +0000 Subject: new man pages --- man/man3/auth.3 | 422 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 422 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..50620cc6 --- /dev/null +++ b/man/man3/auth.3 @@ -0,0 +1,422 @@ +.TH AUTH 3 +.SH 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\- 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(void); +.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(AuthRpc *rpc); +.PP +.B +#include <9pclient.h> +.PP +.B +CFsys* fsamount(int fd, char *aname); +.PP +.B +CFsys* nsamount(char *name, char *aname); +.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 is meaningful only on Plan 9. +.\" 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, as opened by +.IR auth_allocrpc. +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 +.IR auth_allocrpc . +.I Auth_allocrpc +arranges a connection to +.IR factotum , +either by opening +.B /mnt/factotum/rpc +or by using +.IR 9pclient (3) +to connect to a +.B factotum +service posted in the current name space. +The returned connection +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 factotum +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. +.PP +.I Fsamount +and +.I nsamount +are like +.I fsmount +and +.I nsmount +(see +.IR 9pclient (3)) +but use +.I factotum +to authenticate to the file servers. +.SH SOURCE +.B \*9/src/libauth +.SH SEE ALSO +.IR factotum (4), +.IR authsrv (3) +.SH DIAGNOSTICS +These routines set +.IR errstr . -- cgit v1.2.3