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
#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, login_cap_t *lc, char
*name,
char *type);
int
auth_cat(char *file);
void
auth_checknologin(login_cap_t *lc);
char *
auth_mkvalue(char *value);
auth_session_t *
auth_verify(auth_session_t *as, char *style, char *name,
...);
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.
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().
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
the
/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()
function
(see auth_subr(3)). 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()
function (see
auth_subr(3)). The, possibly created, BSD Authentication
session is returned.
The auth_getstate() or auth_close() function (see
auth_subr(3))
should be used to determine the outcome of the authentication request.
The auth_mkvalue() function takes a null terminated string
pointed to by
value and returns a null 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.
auth_subr(3), getpwent(3), pw_dup(3)
The auth_approval(), auth_usercheck(), auth_userokay(), and
auth_userchallenge() 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, 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().
OpenBSD 3.6 March 26, 1997
[ Back ] |
