auth(3) - Plan 9 from User Space

| 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/lib/plan9/src/libauth`
SEE ALSO
| factotum(4), authsrv(3)
DIAGNOSTICS
| These routines set errstr.