Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
AUTH(3)			   Library Functions Manual		       AUTH(3)

       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_ge-
       tuserpasswd,  auth_getinfo,  fsauth_proxy,   fsfauth_proxy,   fsamount,
       nsamount- routines for authenticating users

       #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);

       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 suc-
       cessful 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	facto-
       tum 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	invok-
       ing 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

       Supply to auth_respond a	challenge string and the fmt and args specify-
       ing  a  key, and	it will	use factotum to	return the proper user and re-

       Auth_userpasswd verifies	a simple  user/password	 pair.	 Auth_getuser-
       passwd 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  li-
       brary 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

       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 de-

       Fsamount	 and  nsamount	are like fsmount and nsmount (see 9pclient(3))
       but use factotum	to authenticate	to the file servers.


       factotum(4), authsrv(3)

       These routines set errstr.



Want to link to this manual page? Use this URL:

home | help