auth_getvalue man page on OpenBSD

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

BSD_AUTH(3)		  OpenBSD Programmer's Manual		   BSD_AUTH(3)

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

SYNOPSIS
     #include <sys/types.h>
     #include <login_cap.h>
     #include <bsd_auth.h>

     auth_session_t *
     auth_open(void);

     int
     auth_close(auth_session_t *as);

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

     char *
     auth_challenge(auth_session_t *as);

     quad_t
     auth_check_change(auth_session_t *as);

     quad_t
     auth_check_expire(auth_session_t *as);

     void
     auth_clean(auth_session_t *as);

     void
     auth_clrenv(auth_session_t *as);

     void
     auth_clroption(auth_session_t * as, char *name);

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

     int
     auth_getstate(auth_session_t *as);

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

     void
     auth_set_va_list(auth_session_t *as, va_list ap);

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

     void
     auth_setenv(auth_session_t *as);

     int
     auth_setitem(auth_session_t *as, auth_item_t item, char *value);

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

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

     void
     auth_setstate(auth_session_t *as, int state);

DESCRIPTION
     These functions provide the lower level interface to the BSD
     Authentication 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 authenticated
		      for access and was not expected to be.  This is returned
		      by login scripts that allow changing of the user's
		      password, for instance.  This value is stripped off for
		      normal returns.

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

     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 secure_path(3)
	     function.

     ...     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 calls
     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 out,
     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.

     Note that while auth_call() will zero out the copies it makes of
     sensitive information, such as plain text passwords, after it is sent, it
     is the responsibility of the caller to zero out the original copies of
     this sensitive information.  Due to the mechanics of the auth_call()
     function, this data must be zeroed before auth_call() is called.  The
     safest place to zero out sensitive information is immediately after it
     has been passed to auth_setdata().

     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 indicate 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 auth_getvalue()
     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
     call.

     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
     (/bin/sh).

     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 the
     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 session.

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

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

     AUTH_INTERACTIVE  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 subroutines.

     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() function)
     the values from the previous login script are lost.  (See login.conf(5)
     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 name=value.

     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() or
     auth_check_change()) it returns NULL.  Note that the memory containing
     the password file entry is freed by a call to auth_close() or
     auth_clean().

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

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

CAVEATS
     The auth_check_change() and auth_check_expire() functions call getpwnam()
     or getpwuid(), overwriting the static storage used by the getpwent(3)
     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 the
     auth_setpwd(3) function to copy the passwd struct into as.

OpenBSD 4.9			 July 15, 2009			   OpenBSD 4.9
[top]

List of man pages available for OpenBSD

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]
Tweet
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