interface to the BSD Authentication
*as, char *path,
* as, char
struct passwd *
*as, void *ptr,
*as, char *name,
*as, struct passwd
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
The session pointer must be passed to all other BSD
Authentication functions called. The
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:
- 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
function. 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, for instance. 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 by calling
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 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.
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
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
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
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
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
auth_call() is called. 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 “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
The data read from the back channel is also
used by the
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
only contains two values:
PATH is set to
the default path (/bin and
/usr/bin) while the
set to the default system shell (/bin/sh).
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
auth_call() function. The generated
challenge is returned.
NULL is returned on error or
if no challenge was generated.
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
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
function clears any requests set by a login script for environment variables
to be set.
function clears the previously set option name.
function clears all previously set options.
function returns the value of item. The
item may be one of:
- The latest challenge, if any, set for the session.
- 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.
- 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
NULLor “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.
- 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 interactive service.
- 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.
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.)
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
function will call va_end(3) on ap.
function makes a copy of len bytes of data pointed to
by ptr for use by
The data will be passed on the back channel to the next login script
function adds/deletes any environment variables requested by the login
script to the current environment.
function assigns value to the specified
item. The items are described above with the
auth_getitem() function. In addition, if
item is cleared. If value is
NULL and item is
AUTH_ALL then all items are cleared.
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:
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
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
auth_setpwd() or implicitly via
auth_check_change()), it returns
NULL. Note that the memory containing the password
file entry is freed by a call to
sets the sessions state to state. Typically this is
AUTH_OKAY or 0.
authenticate(3), login_cap(3), pw_dup(3), login.conf(5)