These functions provide the lower level interface to the BSD
They all operate on a BSD Authentication session pointer,
which is returned by
The session pointer
must be passed to all other BSD Authentication functions called.
if it was unable to allocate memory for the session.
The session is terminated by the
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
The user was authenticated.
The user was authenticated with a root instance.
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
In addition to the values above, it also may contain the bits:
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,
This value is stripped off for normal returns.
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.
The user's account has expired.
The user's password has expired and needs to be changed.
A session may be cleaned
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
The remaining functions are described in alphabetical order.
The fundamental function for doing BSD Authentication is
In addition to the pointer to the BSD Authentication session, it takes
the following parameters:
The full path name of the login script to run.
The call will fail if
does not pass the requirements of the
The remaining arguments, which should be of type
and terminated with a
are passed to the login script at the end of the command line.
function, after verifying the
creates a bi-directional pipe (socketpair) which is located on
file descriptor 3 for the child (the login script).
This is known as the
The actual command line passed to the child is made up of
The parameters passed to
have appended to them any arguments specified by the
These are typically the variable arguments passed to the function
Any option values set by the
function are inserted between the first argument (the command
name) and the second argument with a preceding
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
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,
reads up to 8192 bytes of data from the back channel.
The state of the session is determined from this data (see
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
Note that while
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
function, this data must be zeroed
The safest place to zero out sensitive information is immediately
after it has been passed to
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
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
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
The data read from the back channel is also used by the
Subsequent calls to
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
only contains two values:
is set to the default path
is set to the default system shell
function queries the login script defined by the current
for a challenge for the user specified by
(See below for the setting of the
It internally uses the
The generated challenge is returned.
is returned on error or if no challenge was generated.
The challenge can also be extracted by the
function, which simply returns the last challenge generated
for this session.
functions check the password expiration (change) and account expiration
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
as well as clearing any bits which would indicate the authentication was
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.
function clears any requests set by a login script for
environment variables to be set.
function clears the previously set option
function clears all previously set options.
function returns the value of
may be one of:
The latest challenge, if any, set for the session.
The class of the user, as defined by the
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
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.
The name of the user being authenticated.
The name should include the instance, if any, that is being requested.
The service requesting the authentication.
Initially it is set to the default service which provides the traditional
The style of authentication being performed, as defined by the
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.
function returns the value, if any, associated with the specified internal
These variables are set by login scripts.
When a new login script is run
the values from the previous login script are lost.
for details on internal variables.)
function establishes a variable argument list to be used by the
It is intended to be used by functions which need to call
but take a variable number of arguments themselves.
Since the arguments are not copied, the call to
must be placed within the scope of
function will call
function makes a copy of
bytes of data pointed to by
for use by
The data will be passed on the back channel to the next login script called.
function adds/deletes any environment variables requested by the
login script to the current environment.
to the specified
The items are described above with the
In addition, if
then all items are cleared.
function requests that the option
be set with the value of
when a script is executed by
The actual arguments to the script will be placed at the beginning
of the argument vector.
For each option two arguments will be issued:
establishes the password file entry for the authentication session.
If the name has already been set by
argument may be
else it must be the password entry to use.
retrieves the saved password file entry for the authentication session.
If no entry has been saved (either explicitly via
or implicitly via
Note that the memory containing the password file entry is freed by
a call to
sets the sessions state to
Typically this is either
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
function or use the
function to copy the passwd struct into