These functions provide a simplified interface to the BSD Authentication
system
(see bsd_auth(3)).
The
auth_userokay();
function provides a single function call interface.
Provided with a user's name in
name,
and an optional
style,
type,
and
password,
the
auth_userokay();
function returns a simple yes/no response.
A return value of 0 implies failure; a non-zero return value implies success.
If
style
is not
NULL,
it specifies the desired style of authentication to be used.
If it is
NULL
then the default style for the user is used.
In this case,
name
may include the desired style by appending it to the user's name with a
single colon
(‘\:’)
as a separator.
If
type
is not
NULL
then it is used as the authentication type (such as
“auth-myservice)”.
If
password
is
NULL
then
auth_userokay();
operates in an interactive mode with the user on standard input, output,
and error.
If
password
is specified,
auth_userokay();
operates in a non-interactive mode and only tests the specified passwords.
This non-interactive method does not work with challenge-response
authentication styles.
For security reasons, when a
password
is specified,
auth_userokay();
will zero out its value before it returns.
The
auth_usercheck();
function operates the same as the
auth_userokay();
function except that it does not close the BSD Authentication session created.
Rather than returning the status of the session, it returns
a pointer to the newly created BSD Authentication session.
The
auth_userchallenge();
function takes the same
name, style,
and
type
arguments as does
auth_userokay();.
However, rather than authenticating the user, it returns a possible
challenge in the pointer pointed to by
challengep.
The return value of the function is a pointer to a newly created
BSD Authentication session.
This challenge, if not
NULL,
should be displayed to the user.
In any case, the user should provide a password which is
the
response
in a call to
auth_userresponse();.
In addition to the password, the pointer returned by
auth_userchallenge();
should be passed in as
as
and the value of
more
should be non-zero if the program wishes to allow more attempts.
If
more
is zero then the session will be closed.
The
auth_userresponse();
function closes the BSD Authentication session and has the same
return value as
auth_userokay();.
For security reasons, when a
response
is specified,
auth_userresponse();
will zero out its value before it returns.
The
auth_approval();
function calls the approval script for the user of the specified
type.
The string
“approve-”
will be prepended to
type
if missing.
The resulting type is used to look up an entry in
/etc/login.conf
for the user's class.
If the entry is missing, the generic entry for
“approve”
will be used.
The
name
argument will be passed to the approval program as the name of the user.
The
lc
argument points to a login class structure.
If it is
NULL
then a login class structure will be looked up for the class of
user
name.
The
auth_approval();
function returns a value of 0 on failure to approve the user.
Prior to actually calling the approval script, the account's
expiration time, the associated nologin file, and existence
of the account's home directory
(
if
requirehome
is set for this class
)
are checked.
Failure on any of these points causes the
auth_approval();
function to return a value of 0 and not actually call the approval script.
The
auth_cat();
function opens
file
for reading and copies its contents to standard output.
It returns 0 if it was unable to open
file
and 1 otherwise.
The
auth_checknologin();
function must be provided with a pointer to a login class.
If the class has a
“nologin”
entry defined and it points to a file that can be opened,
the contents of the file will be copied to standard output and
exit(3)
will be called with a value of 1.
If the class does not have the field
“ignorenologin”
and the file
/etc/nologin
exists its contents will be copied to standard output and
exit(3)
will be called with a value of 1.
The
auth_verify();
function is a front end to the
auth_call(3)
function.
It will open a BSD Authentication session, if needed, and will set
the style and user name based on the
style
and
name
arguments, if not
NULL.
Values for the style and user name in an existing BSD Authentication
session will be replaced and the old values freed (if the calling program
has obtained pointers to the style or user name via
auth_getitem(3),
those pointers will become invalid).
The variable arguments are passed to
auth_call();
via the
auth_set_va_list(3)
function.
The, possibly created, BSD Authentication session is returned.
The
auth_getstate(3)
or
auth_close(3)
function
should be used to determine the outcome of the authentication request.
The
auth_mkvalue();
function takes a NUL-terminated string pointed to by
value
and returns a NUL-terminated string suitable for passing
back to a calling program on the back channel.
This function is for use by the login scripts themselves.
The string returned should be freed by
free(3)
when it is no longer needed.
A value of
NULL
is returned if no memory was available for the new copy of the string.
The
auth_approval();,
auth_usercheck();,
auth_userokay();,
and
auth_userchallenge();
functions call
getpwnam(3)
or
getpwuid(3),
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, for
auth_approval();
and
auth_usercheck();
only, use the
auth_setpwd(3)
function to copy the passwd struct into a BSD Authentication session structure
which can then be passed to
auth_approval();
or
auth_usercheck();.