auth man page on Plan9

Man page or keyword search:  
man Server   549 pages
apropos Keyword Search (all sections)
Output format
Plan9 logo
[printable version]

AUTH(2)								       AUTH(2)

       amount,	 newns,	  addns,   login,  noworld,  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 -  rou‐
       tines for authenticating users

       #include <u.h>
       #include <libc.h>
       #include <auth.h>

       int	      newns(char *user, char *nsfile);

       int	      addns(char *user, char *nsfile);

       int	      amount(int fd, char *old, int flag, char *aname);

       int	      login(char *user, char *password, char *namespace);

       int	      noworld(char *user);

       AuthInfo*  auth_proxy(int fd, AuthGetkey *getkey, char *fmt, ...);

       AuthInfo*  fauth_proxy(int fd, AuthRpc *rpc, AuthGetkey *getkey,
		      char *params);

       AuthRpc*	  auth_allocrpc(int afd);

       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(int fd);

       This  library,  in  concert  with  factotum(4), is used to authenticate
       users.  It provides the primary interface to factotum.

       Newns builds  a	name  space  for  user.	  It  opens  the  file	nsfile
       (/lib/namespace is used if nsfile is null), copies the old environment,
       erases the current name space, sets the environment variables user  and
       home,  and  interprets the commands in nsfile.  The format of nsfile is
       described in namespace(6).

       Addns also interprets and executes  the	commands  in  nsfile.	Unlike
       newns  it  applies  the	command	 to the current name space rather than
       starting from scratch.

       Amount is like mount but	 performs  any	authentication	required.   It
       should  be used instead of mount whenever the file server being mounted
       requires authentication.	 See bind(2) for a definition of the arguments
       to mount and amount.

       Login  changes the user id of the process user and recreates the names‐
       pace using  the	file  namespace	 (default  /lib/namespace).   It  uses
       auth_userpasswd and auth_chuid.

       Noworld	returns	 1  if the user is in the group noworld in /adm/users.
       Otherwise, it returns 0.	 Noworld is used by telnetd and ftpd  to  pro‐
       vide sandboxed access for some users.

       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 can
       be passed to the cap(3) device to change the user id  of	 the  process.
       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

       Auth_proxy  proxies  an	authentication	conversation  between a remote
       server reading and writing fd and a factotum file.  The	factotum  file
       used  is	 /mnt/factotum/rpc.   An  sprint (see print(2)) 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 with the	fd  of
       an open factotum connection.  It is freed using auth_freerpc.  Individ‐
       ual 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

       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

       Auth_userpasswd verifies a simple  user/password	 pair.	 Auth_getuser‐
       passwd retrieves a user/password pair from factotum if permitted:

	      typedef struct UserPasswd {
		  char	  *user;
		  char	  *passwd;
	      } UserPasswd;

       Auth_getinfo  reads  an AuthInfo message from fd and converts it into a
       structure.  It is only used by the other routines in this library  when
       communicating with factotum.

       Auth_freeAI  is	used  to free an AuthInfo structure returned by one of
       these routines.	 Similary  auth_freechal  frees	 a  challenge/response


       factotum(4), authsrv(2), bind(2)

       These routines set errstr.

                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server Plan9

List of man pages available for Plan9

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
Vote for polarhome
Free Shell Accounts :: the biggest list on the net