AUTH(3) AUTH(3)
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
SYNOPSIS
#include <u.h>
#include <libc.h>
#include <auth.h>
AuthInfo* auth_proxy(int fd, AuthGetkey *getkey, char *fmt,
...);
AuthInfo* fauth_proxy(int fd, AuthRpc *rpc, AuthGetkey
*getkey,
char *params);
AuthRpc* auth_allocrpc(void);
void auth_freerpc(AuthRpc *rpc);
uint auth_rpc(AuthRpc *rpc, char *verb, void *a,
int n);
int auth_getkey(char *proto, char *dom);
int (*amount_getkey)(char*, char*);
void auth_freeAI(AuthInfo *ai);
int auth_chuid(AuthInfo *ai, char *ns);
Chalstate* auth_challenge(char *fmt, ...);
AuthInfo* auth_response(Chalstate*);
void auth_freechal(Chalstate*);
int auth_respond(void *chal, uint nchal, char
*user, uint nuser, void *resp, uint nresp, AuthGetkey *get-
key, char *fmt, ...);
AuthInfo* auth_userpasswd(char*user, char*password);
UserPasswd* auth_getuserpasswd(AuthGetkey *getkey,
char*fmt, ...);
Page 1 Plan 9 (printed 12/22/24)
AUTH(3) AUTH(3)
AuthInfo* auth_getinfo(AuthRpc *rpc);
#include <9pclient.h>
AuthInfo* fsauth_proxy(CFid *fid, AuthGetkey *getkey, char
*fmt, ...);
AuthInfo* fsfauth_proxy(CFid *fid, AuthRpc *rpc, AuthGetkey
*getkey,
char *params);
CFsys* fsamount(int fd, char *aname);
CFsys* nsamount(char *name, char *aname);
DESCRIPTION
This library, in concert with factotum(4), is used to
authenticate users. It provides the primary interface to
factotum.
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 */
int nsecret; /* 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 is meaningful only on Plan 9. 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, as
opened by auth_allocrpc. An sprint (see print(3)) 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 authentica-
tions. This is necessary, for example, for newns which must
Page 2 Plan 9 (printed 12/22/24)
AUTH(3) AUTH(3)
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. Auth_allocrpc arranges a connection to
factotum, either by opening /mnt/factotum/rpc or by using
9pclient(3) to connect to a factotum service posted in the
current name space. The returned connection 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;
char chal[MAXCHLEN];
int nchal;
void *resp;
int nresp;
/* for implementation only */
int afd;
AuthRpc *rpc;
char userbuf[MAXNAMELEN];
int userinchal;
};
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 speci-
fied as an attribute in the key template and apop, cram, and
chap expect it in the user field of the arg to
Page 3 Plan 9 (printed 12/22/24)
AUTH(3) AUTH(3)
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 factotum 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.
Fsauth_proxy and fsfauth_proxy are like auth_proxy and
fauth_proxy but execute the protocol on a CFid* (see
9pclient(3)) instead of a file descriptor.
Fsamount and nsamount are like fsmount and nsmount (see
9pclient(3)) but use factotum to authenticate to the file
servers.
SOURCE
/usr/local/plan9/src/libauth
SEE ALSO
factotum(4), authsrv(3)
DIAGNOSTICS
These routines set errstr.
Page 4 Plan 9 (printed 12/22/24)