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 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. Non-optional arguments such as user should be prefixed by a "--" argument so that getopt(3) will not attempt to interpret them as optional flags.
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=valueOnce 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.