AUTH_COMPAT(3) BSD Programmer's Manual AUTH_COMPAT(3)NAME
auth_approve, auth_check, auth_clropts, auth_env, auth_response,
auth_rmfiles, auth_scan, auth_script, auth_script_data, auth_setopt,
auth_value - deprecated BSD Authentication interface
SYNOPSIS
#include <login_cap.h>
int
auth_approve(login_cap_t *lc, char *fullname, char *service);
int
auth_check(char *fullname, char *class, char *style, char *service,
int *stat);
void
auth_clropts();
void
auth_env();
int
auth_response(char *fullname, char *class, char *style, char *service,
int *stat, char *challenge, char *response);
void
auth_rmfiles();
int
auth_scan(int okay);
int
auth_script(char *path, ...);
int
auth_script_data(char *data, int nbytes, char *path, ...);
int
auth_setopt(char *name, char *value);
char *
auth_value(char *name);
DESCRIPTION
These functions provide the deprecated interface to the BSD Authentica-
tion system. They are only provided for backwards compatibility with ex-
isting software and should not be used in new code.
BSD Authentication is performed through external login scripts with ac-
cess controlled by the /etc/login.conf file. See login.conf(5) for a de-
scription of the interface to these external programs.
THE PARAMETERS
The following parameters are used in the various routines:
challenge A null terminated string representing the challenge issued to
the user.
class The users login class. See login.conf(5) for more details.
data A pointer to arbitrary data to be passed to the login script
on file descriptor 3 (the ``backchannel''). The data may con-
tain NULs.
fullname The full name of the user being authenticated, including any
instance.
lc A pointer to the login_cap_t returned by the login_get-
class(3) routine. This value can be NULL in which case the
fullname parameter is used to lookup the login class for the
user.
name The name of a variable or option.
nbytes The number of bytes the data parameter is pointing to.
okay The value to return if no explicit authentication or rejec-
tion message is received from the login_script.
path
response A null terminated string representing the response to the
challenge that was issued to the user.
service The type of service being requested of the login script. See
login.conf(5) for a description of the various services. A
NULL may be passed to indicate the default service should be
used. The default service requires that standard input, out-
put, and error be available for their normal interaction with
the user.
stat If not NULL, the full return status is stored to the location
to which stat points. The return values are a subset of the
status such that any return value greater than 0 indicates
the authentication was successful. The additional informa-
tion contained in the full status indicates how to treat a
failure.
style The style of authentication to be used. See login.conf(5)
for a description of the various styles. This value must not
be NULL, there is no hard coded default style.
value The value to be associated with the specified name.
STATUS
The status is made up of one or more 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 sub-
ject to eavesdropping attacks (such as provided by token
cards).
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 in-
stance. 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 re-
sponse retrieved, and the result verified. This value is
stripped off for normal returns.
THE FUNCTIONSauth_approve()
Run the approval script for the specified service, a return
greater than 0 indicates the user was approved.
auth_check()
Run the login script specified by the style for the user. A
return value greater than 0 indicates success. Use the value
pointed to by stat to determine if a rejection was silent or
a challenge was issued. Use the auth_value() function to re-
trieve any generated challenge.
auth_clropts()
Clear any options stored for sending to the login script.
auth_env() Set any environment variables specified by the last lo-
gin_script to have run.
auth_response()
Verify a response from the user for the specified challenge.
The challenge can be the NULL string if the user provided a
response prior to the issuing of challenge (such as from a
PortMaster).
auth_rmfiles()
Remove any files generated by the login script. This should
only be done if the user was ultimately denied access.
auth_scan()
Scan the data returned from a login script and return the
status determined. If no status was set, return okay. (Note
that okay should always be 0 when checking authentication,
approval scripts use the value of AUTH_OKAY since no return
from them implies the user was accepted.)
auth_script()
Execute the requested script, reading responses on file de-
scriptor 3. Any options specified by the auth_setopt() func-
tion are inserted between the 0th and first argument. Each
option is preceeded by the -v flag.
auth_script_data()
The same as auth_script() except the specified data is writ-
ten to file descriptor 3 prior to reading the response. The
data typically should be of the form ``challenge response ''.
auth_setopt()
When calling a login script, insert the following option on
the command line: -v name=value
Search the response from the last login script for the value
associated with the given name. See login.conf(5) for a list
of possible names.
ISSUES
These routines use global state so only one BSD Authentication session
can be effectively used at one time. While auth_check() provides a sim-
ple single function call authentication interface, it depends on standard
input, output and error. The programmatic interface, in particular when
challenges are issued, is complex and overly burdensome. The new BSD Au-
thentication interface provides a much better interface.
SEE ALSOauthenticate(3), auth_subr(3), login_cap(3), login.conf(5)
