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 is used to authenticate users.  It pro-
       vides the primary interface to factotum.

       The following routines use the AuthInfo structure returned after	a suc-
       cessful authentication by

       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 of fmt and the variable arg list	yields
       a key template (see specifying the key to use.  The template must spec-
       ify 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 to connect to a factotum service posted in the current name
       space.  The returned connection is freed	using auth_freerpc.   Individ-
       ual commands can	be sent	to 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

       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 instead of a file descriptor.

       Fsamount	 and nsamount are like fsmount and nsmount (see	but use	facto-
       tum to authenticate to the file servers.


       These routines set errstr.



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

home | help