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

SYNOPSIS

#include <u.h>
#include <libc.h>
#include <auth.h>

intnewns(char ∗user, char ∗nsfile);

intaddns(char ∗user, char ∗nsfile);

intamount(int fd, char ∗old, int flag, char ∗aname);

intlogin(char ∗user, char ∗password, char ∗namespace);

intnoworld(char ∗user);

AuthInfo∗auth_proxy(int fd, AuthGetkey ∗getkey, char ∗fmt, ...);

AuthInfo∗fauth_proxy(int fd, AuthRpc ∗rpc, AuthGetkey ∗getkey,
­char ∗params);

AuthRpc∗auth_allocrpc(int afd);

voidauth_freerpc(AuthRpc ∗rpc);

uintauth_rpc(AuthRpc ∗rpc, char ∗verb, void ∗a, int n);

intauth_getkey(char ∗proto, char ∗dom);

int(∗amount_getkey)(char∗, char∗);

voidauth_freeAI(AuthInfo ∗ai);

intauth_chuid(AuthInfo ∗ai, char ∗ns);

Chalstate∗auth_challenge(char ∗fmt, ...);

AuthInfo∗auth_response(Chalstate∗);

voidauth_freechal(Chalstate∗);

intauth_respond(void ∗chal, uint nchal, char ∗user, uint nuser, void ∗resp, uint nresp, AuthGetkey ∗getkey, char ∗fmt, ...);

AuthInfo∗auth_userpasswd(char∗user, char∗password);

UserPasswd∗auth_getuserpasswd(AuthGetkey ∗getkey, char∗fmt, ...);

AuthInfo∗auth_getinfo(int fd);

DESCRIPTION

This library, in concert with factotum(4), is used to authenticate users. It provides the primary interface to factotum.

­Newns builds a name space for user. It opens the file ­nsfile (/lib/namespace is used if ­nsfile is null), copies the old environment, erases the current name space, sets the environment variables ­user and home, and interprets the commands in nsfile. The format of ­nsfile is described in namespace(6).

­Addns also interprets and executes the commands in nsfile. Unlike ­newns it applies the command to the current name space rather than starting from scratch. 

­Amount is like ­mount but performs any authentication required.  It should be used instead of ­mount whenever the file server being mounted requires authentication.  See bind(2) for a definition of the arguments to ­mount and amount.

­Login changes the user id of the process ­user and recreates the namespace using the file ­namespace (default /lib/nnamespace).  It uses ­auth_userpassword and auth_chuid.

­Noworld returns 1 if the user is in the group ­noworld in /adm/users.  Otherwise, it returns 0.  ­Noworld is used by telnetd and ftpd to provide sandboxed access for some users. 

The following routines use the ­AuthInfo structure returned after a successful authentication by factotum(4).

typedef struct
{
char∗cuid;/∗ caller id ∗/
char∗suid;/∗ server id ∗/
char∗cap;/∗ capability ∗/
intnsecret;/∗ length of secret ∗/
uchar∗secret;/∗ secret ∗/
} AuthInfo;

The fields ­cuid and ­suid point to the authenticated ids of the client and server.  ­Cap is a capability returned only to the server.  It can be passed to the cap(3) device to change the user id of the process. ­Secret is an 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. 

­Auth_proxy proxies an authentication conversation between a remote server reading and writing ­fd and a ­factotum file.  The ­factotum file used is /mnt/factotum/rpc.  An ­sprint (see print(2)) of ­fmt and the variable arg list yields a key template (see factotum(4)) specifying the key to use. The template must specify at least the protocol ( proto=xxx) and the role (either ­role=client or role=server).  ­Auth_proxy either returns an allocated ­AuthInfo structure, or sets the error string and returns nil. 

­Fauth_proxy can be used instead of ­auth_proxy if a single connection to ­factotum will be used for multiple authentications.  This is necessary, for example, for ­newns which must open the ­factotum file before wiping out the namespace.  ­Fauth_proxy takes as an argument a pointer to an ­AuthRPC structure which contains an fd for an open connection to ­factotum in addition to storage and state information for the protocol.  An ­AuthRPC structure is obtained by calling ­auth_allocrpc with the fd of an open ­factotum connection.  It is freed using auth_freerpc. Individual commands can be sent to factotum(4) by invoking auth_rpc.

Both ­auth_proxy and ­fauth_proxy take a pointer to a routine, getkey, to invoke should ­factotum not posess a key for the authentication.  If ­getkey is nil, the authentication fails.  ­Getkey is called with a key template for the desired key.  We have provided a generic routine, auth_getkey, which queries the user for the key information and passes it to factotum. This is the default for the global variable, amount_getkey, which holds a pointer to the key prompting routine used by amount.

­Auth_chuid uses the ­cuid and ­cap fields of an ­AuthInfo structure to change the user id of the current process and uses ns, default /lib/namespace, to build it a new name space. 

­Auth_challenge and ­auth_response perform challenge/response protocols with factotum. State between the challenge and response phase are kept in the ­Chalstate structure:

struct Chalstate
{
char∗user;
charchal[MAXCHLEN];
intnchal;
void∗resp;
intnresp;
 /∗ for implementation only ∗/
intafd;
AuthRpc∗rpc;
charuserbuf[MAXNAMELEN];
intuserinchal;
};

­Auth_challenge requires a key template generated by an ­sprint of ­fmt and the variable arguments.  It must contain the protocol (proto=xxx) and depending on the protocol, the user name ( user=xxx). ­P9cr and ­vnc expect the user specified as an attribute in the key template and apop, cram, and chap expect it in the ­user field of the arg to auth_response. For all protocols, the response is returned to ­auth_response in the ­resp field of the Chalstate.  ­Chalstate.nresp must be the length of the response. 

Supply to ­auth_respond a challenge string and the fmt and args specifying a key, and it will use ­factotum to return the proper user and response. 

­Auth_userpasswd verifies a simple user/password pair.  ­Auth_getuserpasswd retrieves a user/password pair from ­factotum if permitted. 

­Auth_getinfo reads an ­AuthInfo message from ­fd and converts it into a structure.  It is only used by the other routines in this library when communicating with factotum.

typedef struct UserPasswd {
char∗user;
char∗passwd;
} UserPasswd;

­Auth_freeAI is used to free an ­AuthInfo structure returned by one of these routines.  Similary ­auth_freechal frees a challenge/response state. 

SOURCE

­/sys/src/libauth

SEE ALSO

factotum(4), authsrv(2), bind(2)

DIAGNOSTICS

These routines set errstr.

Plan 9  —  March 29, 2002