1 files changed, 395 insertions, 0 deletions
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 <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 *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 .