*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->OpenBSD man pages -> auth_clrenv (3)              



NAME    [Toc]    [Back]

     auth_open, auth_call, auth_challenge, auth_check_change,
     auth_check_expire,  auth_clean,   auth_close,   auth_clrenv,
     auth_clroptions,  auth_getitem,  auth_getpwd, auth_getstate,
     auth_set_va_list, auth_setdata, auth_setenv, auth_setitem,
     auth_setoption, auth_setpwd, auth_setstate  -  interface  to
the BSD Authentication

SYNOPSIS    [Toc]    [Back]

     #include <login_cap.h>
     #include <bsd_auth.h>

     auth_session_t *

     auth_close(auth_session_t *as);

     auth_call(auth_session_t *as, char *path, ...);

     char *
     auth_challenge(auth_session_t *as);

     auth_check_change(auth_session_t *as);

     auth_check_expire(auth_session_t *as);

     auth_clean(auth_session_t *as);

     auth_clrenv(auth_session_t *as);

     auth_clroption(auth_session_t * as, char *name);

     auth_clroptions(auth_session_t *as);

     char *
     auth_getitem(auth_session_t *as, auth_item_t item);

     struct passwd *
     auth_getpwd(auth_session_t *as);

     auth_getstate(auth_session_t *as);

     char *
     auth_getvalue(auth_session_t *as, char *what);

     auth_set_va_list(auth_session_t *as, va_list ap);

     auth_setdata(auth_session_t *as, void *ptr, size_t len);

     auth_setenv(auth_session_t *as);

     auth_setitem(auth_session_t   *as,  auth_item_t  item,  char

     auth_setoption(auth_session_t *as, char *name, char *value);

     auth_setpwd(auth_session_t *as, struct passwd *pwd);

     auth_setstate(auth_session_t *as, int state);

DESCRIPTION    [Toc]    [Back]

     These functions provide the lower level interface to the BSD
 system.  They all operate on a BSD Authentication  session pointer,
     as,  which  is returned by auth_open().  The session pointer
must be passed
     to all  other  BSD  Authentication  functions  called.   The
auth_open() function
  returns  NULL  if it was unable to allocate memory for
the session.
     The session is  terminated  by  the  auth_close()  function,
which also sets
     any environment variables requested by the login script (assuming the user
 was not rejected) or removes files created by  the  login
script if the
     authentication  was  not  successful.   It returns the final
state of the authentication
 request.  A return value of 0 implies the  user
was not authenticated.
   A  non-zero  return  value is made up of 1 or
more of the following
 values ORed together:

     AUTH_OKAY        The user was authenticated.

     AUTH_ROOTOKAY    The user was authenticated with a root  instance.

     AUTH_SECURE       The user was authenticated via a mechanism
which is not
                      subject to eavesdropping attacks  (such  as
provided by
                      token cards).

     The   full   state   of  the  session  is  returned  by  the
auth_getstate() function.
  In addition to the values above, it also may  contain
the bits:

     AUTH_SILENT       Do  not  report an error, the user was not
                      for access and  was  not  expected  to  be.
This is returned
                      by login scripts that allow changing of the
users password,
 for instance.  This value is stripped
off for normal

     AUTH_CHALLENGE    The  user was not authenticated for access
and a challenge
 was issued.  The challenge should  be
displayed to
                      the user, a response retrieved, and the result verified.
                      This value is stripped off for  normal  returns.

     AUTH_EXPIRED     The user's account has expired.

     AUTH_PWEXPIRED    The  user's password has expired and needs
to be changed.

     A session may be  cleaned  by  calling  auth_clean().   This
function removes
     any  files  created  by  a  login script in this session and
clears all state
     associated with this session, with the exception of the  option settings.
     It  is not necessary to call auth_clean() if auth_close() is

     The remaining functions are described in alphabetical order.

     The  fundamental  function  for  doing BSD Authentication is
auth_call().  In
     addition to the pointer to the BSD  Authentication  session,
it takes the
     following parameters:

     path     The full path name of the login script to run.  The
call will
             fail if path does not pass the requirements  of  the

     ...      The  remaining  arguments,  which should be of type
char * and terminated
 with a NULL are passed to the  login  script
at the end of
             the command line.

     The  auth_call() function, after verifying the path, creates
a bi-directional
 pipe (socketpair) which is located on file descriptor
3 for the
     child (the login script).  This is known as the ``back channel''.  The
     actual command line passed to the child  is  made  up  of  3
parts.  The parameters
  passed to auth_call() following path have appended
to them any
     arguments  specified  by  the  auth_set_va_list()  function.
These are typically
  the  variable  arguments  passed to the function that
     auth_call().  Any option values set by the  auth_setoption()
function are
     inserted  between  the first argument (the command name) and
the second argument
 with a preceding -v flag.  The  name  and  value  are
separated by an

           -v name=value

     Once  the  login script has been spawned, any data specified
by the
     auth_setdata() is written to  the  back  channel.   Multiple
blocks of data
     may  have  been  specified and they will be sent in the same
order they were
     specified.  As the data is sent, the storage for the data is
zeroed out
     and  then freed (the data is zeroed out since it may contain
sensitive information,
 such as a password).  Once any  data  is  written
     auth_call()  reads  up  to  8192 bytes of data from the back
channel.  The
     state of the session is determined from this data  (see  login.conf(5) for
     details).   If  the login script exits with a 0 and does not
specify any
     return state on the back channel, the  state  prior  to  the
call to
     auth_call() is retained.

     The  back  channel  data  may also contain a file descriptor
passed back from
     the login script.  If this is the  case,  the  login  script
will first send
     back  the  string  ``fd'' to indidate that a file descriptor
will be the
     next data item.  The file descriptor will be passed back  to
the next invocation
  of the login script with a number specified by the
-v fd option.
     This  is  used  to  implement  stateful   challenge/response
schemes that require
  a  persistent connection during the challenge and response.  The
     copy of the descriptor in the parent process is closed  when
the child is
     running  to prevent deadlock when file locking is used.  The
descriptor is
     also closed by a call to auth_close() or auth_clean().

     The data read from the back channel  is  also  used  by  the
     and auth_close() functions.  Subsequent calls to auth_call()
will cause
     this data to be lost and overwritten with the new data  read
from the new

     The  environment  passed  to the login script by auth_call()
only contains
     two values: PATH and SHELL.  The PATH is set to the  default
path ( /bin
     and  /usr/bin)  while the SHELL is set to the default system
shell (

     The auth_challenge() function queries the login  script  defined by the
     current  style  for  a  challenge  for the user specified by
name.  (See below
     for the setting of the style and name).  It internally  uses
     auth_call()  function.  The generated challenge is returned.
NULL is returned
 on error or if no challenge was generated.  The challenge can also
     be extracted by the auth_getchallenge() function, which simply returns
     the last challenge generated for this session.

     The auth_check_change()  and  auth_check_expire()  functions
check the password
 expiration (change) and account expiration times.  They
return 0 if
     no change or expiration time is set for the  account.   They
return a negative
  value  of how many seconds have passed since the password or account
     expired.  In this case the state of the  session  is  marked
with either
     AUTH_PWEXPIRED  or AUTH_EXPIRED as well as clearing any bits
which would
     indicate the authentication was successful.  If the password
or account
     has not expired they return the number of seconds left until
the account
     does expire.  The return value of -1 can either indicate the
password or
     account  just  expired or that no password entry was set for
the current

     The auth_clrenv() function clears any requests set by a  login script for
     environment variables to be set.

     The  auth_clroption() function clears the previously set option name.

     The auth_clroptions() function clears all previously set options.

     The  auth_getitem() function returns the value of item.  The
item may be
     one of:

     AUTH_CHALLENGE   The latest challenge, if any, set  for  the

     AUTH_CLASS        The  class  of the user, as defined by the
                      file.  This value is not directly  used  by
BSD Authentication,
  rather,  it is passed to the login
scripts for
                      their possible use.

                      If set to any value  then  the  session  is
tagged as interactive.
   If not set the session is not interactive.
                      When the value is requested  it  is  always
either NULL or
                      ``True''.   The auth subroutines may choose
to provide
                      additional information to  standard  output
or standard
                      error  when  the  session  is  interactive.
There is no
                      functional change in the operation  of  the

     AUTH_NAME         The  name of the user being authenticated.
The name
                      should include the instance, if  any,  that
is being requested.

     AUTH_SERVICE      The service requesting the authentication.
Initially it
                      is set to the default  service  which  provides the traditional
 interactive service.

     AUTH_STYLE        The  style  of  authentication  being performed, as defined
                      by the /etc/login.conf file.  The style determines which
                      login script should actually be used.

     The  value  returned points to private memory and should not
be freed by
     the caller.

     The auth_getvalue() function returns the value, if any,  associated with
     the  specified  internal variable what.  These variables are
set by login
     scripts.  When a new login script is run (by the auth_call()
     the  values  from  the previous login script are lost.  (See
     for details on internal variables.)

     The auth_set_va_list() function establishes a variable argument list to
     be  used  by the auth_call() function.  It is intended to be
used by functions
 which need to call auth_call()  but  take  a  variable
number of arguments
  themselves.   Since the arguments are not copied, the
call to
     auth_call() must be placed within  the  scope  of  ap.   The
auth_call() function
 will call va_end(3) on ap.

     The auth_setdata() function makes a copy of len bytes of data pointed to
     by ptr for use by auth_call().  The data will be  passed  on
the back channel
 to the next login script called.

     The  auth_setenv()  function  adds/deletes  any  environment
variables requested
 by the login script to the current environment.

     The auth_setitem() function assigns value to  the  specified
item.  The
     items  are described above with the auth_getitem() function.
In addition,
     if value is NULL, the item is cleared.  If value is NULL and
item is
     AUTH_ALL then all items are cleared.

     The  auth_setoption() function requests that the option name
be set with
     the value of value when a script is executed by auth_call().
The actual
     arguments  to  the script will be placed at the beginning of
the argument
     vector.  For each option two arguments will  be  issued:  -v

     The function auth_setpwd() establishes the password file entry for the
     authentication session.  If the name has already been set by
     auth_setitem()  then  the  pwd argument may be NULL, else it
must be the
     password entry to use.

     The function auth_getpwd() retrieves the saved password file
entry for
     the authentication session.  If no entry has been saved (either explicitly
 via auth_setpwd() or implicitly  via  auth_check_expire()
     auth_check_change())  it returns NULL.  Note that the memory
     the password file entry is freed by a call  to  auth_close()

     The  function  auth_setstate()  sets  the  sessions state to
state.  Typically
     this is either AUTH_OKAY or 0.

SEE ALSO    [Toc]    [Back]

     authenticate(3), login_cap(3), pw_dup(3), login.conf(5)

CAVEATS    [Toc]    [Back]

     The auth_check_change()  and  auth_check_expire()  functions
call getpwnam()
     or  getpwuid(),  overwriting  the static storage used by the
     family of routines.  The calling program must either make  a
local copy of
     the  passwd struct pointer via the pw_dup(3) function or use
     auth_setpwd(3) function to copy the passwd struct into as.

OpenBSD     3.6                          March      20,      1997
[ Back ]
 Similar pages
Name OS Title
authenticate OpenBSD simplified interface to the BSD Authentication system
auth_verify OpenBSD simplified interface to the BSD Authentication system
auth_userresponse OpenBSD simplified interface to the BSD Authentication system
auth_userokay OpenBSD simplified interface to the BSD Authentication system
auth_usercheck OpenBSD simplified interface to the BSD Authentication system
auth_userchallenge OpenBSD simplified interface to the BSD Authentication system
auth_approval OpenBSD simplified interface to the BSD Authentication system
auth_mkvalue OpenBSD simplified interface to the BSD Authentication system
auth_checknologin OpenBSD simplified interface to the BSD Authentication system
auth_cat OpenBSD simplified interface to the BSD Authentication system
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service