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
#include <login_cap.h>
#include <bsd_auth.h>
auth_session_t *
auth_open();
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);
int
auth_setstate(auth_session_t *as, int state);
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
users 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.
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 indidate 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.
authenticate(3), login_cap(3), pw_dup(3), login.conf(5)
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 3.6 March 20, 1997
[ Back ] |
