| 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 *getkey, char *fmt, ...);

` `AuthInfo* auth_userpasswd(char*user, char*password);

` `UserPasswd* auth_getuserpasswd(AuthGetkey *getkey, char*fmt, ...);

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