plan9port/man/man3/auth.3

.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, fsauth_proxy, fsfauth_proxy, fsamount, nsamount\- 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
AuthInfo*	fsauth_proxy(CFid *fid, AuthGetkey *getkey, char *fmt, ...);
.PP
.B
AuthInfo*	fsfauth_proxy(CFid *fid, AuthRpc *rpc, AuthGetkey *getkey,
.br
.B			char *params);
.PP
.B
CFsys*	fsamount(int fd, char *aname);
.PP
.B
CFsys*	nsamount(char *name, char *aname);
.SH DESCRIPTION
.PP
This library, in concert with
.MR 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
.MR 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
.MR print (3) )
of 
.I fmt
and the variable arg list yields a key template (see
.MR 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 
.MR 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
.MR 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 Fsauth_proxy
and
.I fsfauth_proxy
are like
.I auth_proxy
and
.I fauth_proxy
but execute the protocol on a
.B CFid*
(see
.MR 9pclient (3) )
instead of a file descriptor.
.PP
.I Fsamount
and
.I nsamount
are like
.I fsmount
and
.I nsmount
(see
.MR 9pclient (3) )
but use
.I factotum
to authenticate to the file servers.
.SH SOURCE
.B \*9/src/libauth
.SH SEE ALSO
.MR factotum (4) ,
.MR authsrv (3)
.SH DIAGNOSTICS
These routines set
.IR errstr .