NAME
auth_approval,
auth_cat, auth_checknologin,
auth_mkvalue,
auth_userchallenge,
auth_usercheck,
auth_userokay,
auth_userresponse,
auth_verify —
simplified interface to the BSD
Authentication system
SYNOPSIS
#include
<sys/types.h>
#include <login_cap.h>
#include <bsd_auth.h>
int
auth_userokay(char
*name, char *style,
char *type,
char *password);
auth_session_t *
auth_userchallenge(char
*name, char *style,
char *type,
char **challengep);
auth_session_t *
auth_usercheck(char
*name, char *style,
char *type,
char *password);
int
auth_userresponse(auth_session_t
*as, char
*response, int
more);
int
auth_approval(auth_session_t
*as, struct login_cap
*lc, char *name,
char *type);
int
auth_cat(char
*file);
void
auth_checknologin(struct
login_cap *lc);
char *
auth_mkvalue(char
*value);
auth_session_t *
auth_verify(auth_session_t
*as, char *style,
char *name,
...);
DESCRIPTION
These functions provide a simplified interface to the
BSD Authentication system (see
auth_subr(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.