Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
AUTHENTICATE(3)           OpenBSD Programmer's Manual          AUTHENTICATE(3)

     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>

     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);

     auth_userresponse(auth_session_t *as, char *response, int more);

     auth_approval(auth_session_t *as, login_cap_t *lc, char *name,
             char *type);

     auth_cat(char *file);

     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 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 cre-
     ated 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 lookup an entry in the
     /etc/login.conf for the user's class.  If the entry is missing the gener-
     ic 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() func-
     tion 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 other-

     The auth_checknologin() function must be provided with a pointer to a lo-
     gin 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 argu-
     ments, if not NULL. The variable arguments are passed to auth_call() via
     the auth_set_va_list() function (see auth_subr(3)). The, possibly creat-
     ed, 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 lo-
     gin 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() or getpwuid(), overwriting
     the static storage used by the getpwent(3) family of routines.  The call-
     ing 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().

     auth_subr(3), getpwent(3), pw_dup(3)

OpenBSD 3.1                     March 26, 1997                               2


Want to link to this manual page? Use this URL:

home | help