AUTH_OPEN(3) | Library Functions Manual | AUTH_OPEN(3) |
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
<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);
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
AUTH_ROOTOKAY
AUTH_SECURE
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
AUTH_CHALLENGE
AUTH_EXPIRED
AUTH_PWEXPIRED
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:
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=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
AUTH_CLASS
AUTH_INTERACTIVE
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
AUTH_SERVICE
AUTH_STYLE
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.
November 24, 2015 | OpenBSD-current |