423 lines
8 KiB
Text
423 lines
8 KiB
Text
.TH AUTH 2
|
|
.SH NAME
|
|
amount, newns, addns, login, noworld, procsetuser, 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_respondAI, 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
|
|
int procsetuser(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 *params);
|
|
.PP
|
|
.B
|
|
int (*amount_getkey)(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
|
|
int auth_respondAI(void *chal, uint nchal, char *user, uint nuser, void *resp, uint nresp, AuthInfo **ai, 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*);
|
|
.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 to
|
|
.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
|
|
.I Procsetuser
|
|
changes the user id of the process to
|
|
.I user
|
|
but keeps the namespace unchanged.
|
|
Only hostowner can change the user to
|
|
anything other than the
|
|
.B none
|
|
user.
|
|
.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 possess 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_respondAI
|
|
is like
|
|
.I auth_respond
|
|
but has an additional
|
|
.I ai
|
|
output parameter to return an
|
|
.I AuthInfo
|
|
structure on success that holds protocol specific secret keys
|
|
derived from the exchange. The returned
|
|
.I AuthInfo
|
|
structure should be freed with
|
|
.I auth_freeAI
|
|
by the caller.
|
|
.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 rpc
|
|
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 .
|