auth_usercheck man page on OpenBSD

Man page or keyword search:  
man Server   11362 pages
apropos Keyword Search (all sections)
Output format
OpenBSD logo
[printable version]

AUTHENTICATE(3)		  OpenBSD Programmer's Manual	       AUTHENTICATE(3)

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 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.

SEE ALSO
     auth_subr(3), getpwent(3), pw_dup(3)

CAVEATS
     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().

OpenBSD 4.9		       January 24, 2011			   OpenBSD 4.9
[top]

List of man pages available for OpenBSD

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net