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

You are viewing proxied material from sdf.org. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.