new man pages

1 files changed, 422 insertions, 0 deletions

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 <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(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 .