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
‘=’:
Fl v Ar 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
beforeauth_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.
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.