From 058b0118a52061ad57694c01fc8763b22b789c4d Mon Sep 17 00:00:00 2001 From: rsc Date: Mon, 3 Jan 2005 06:40:20 +0000 Subject: Some man pages. --- man/man3/auth.3 | 395 -------------------------------------------------------- 1 file changed, 395 deletions(-) delete mode 100644 man/man3/auth.3 (limited to 'man/man3/auth.3') diff --git a/man/man3/auth.3 b/man/man3/auth.3 deleted file mode 100644 index 1fe81f97..00000000 --- a/man/man3/auth.3 +++ /dev/null @@ -1,395 +0,0 @@ -.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 (3) -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 (3)) -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 /usr/local/plan9/src/libauth -.SH SEE ALSO -.IR factotum (4), -.IR authsrv (3), -.IR bind (3) -.SH DIAGNOSTICS -These routines set -.IR errstr . -- cgit v1.2.3