Subversion Repositories planix.SVN

.TH AUTH 2

.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/namespace ).

It uses

.I auth_userpasswd

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

.IP

.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

.PP

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:

.IP

.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

.PP

.I Auth_challenge

requires a key template generated by an

.B sprint

of

.I fmt

and the variable arguments.  It must contain the protocol

(\fLproto=\fIxxx\fR)

and depending on the protocol, the user name (\c

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

.IP

.ne 8

.EX

.ta 4n +4n +4n +4n +4n +4n +4n +4n +4n

typedef struct UserPasswd {

	char	*user;

	char	*passwd;

} UserPasswd;

.EE

.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

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