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

FreeBSD Manual Pages

  
 
  

home | help
AUTH(3)			   Library Functions Manual		       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_ge-
       tuserpasswd,  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 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
       response.

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

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

       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.

								       AUTH(3)

NAME | SYNOPSIS | DESCRIPTION | SOURCE | SEE ALSO | DIAGNOSTICS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=auth&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help