pam_get_user(3pam) [opensolaris man page]

pam_get_user(3PAM)					       PAM Library Functions						pam_get_user(3PAM)

NAME

       pam_get_user - PAM routine to retrieve user name

SYNOPSIS

       cc [ flag ... ] file ...  -lpam [ library ... ]
       #include <security/pam_appl.h>

       int pam_get_user(pam_handle_t *pamh, char **user,
	    const char *prompt);

DESCRIPTION

       The  pam_get_user()  function  is used by  PAM service modules to retrieve the current user name from the  PAM handle. If the user name has
       not been set with pam_start() or  pam_set_item(), the PAM conversation function will be used to prompt the user for the user name with  the
       string  "prompt". If prompt is  NULL, then pam_get_item() is called and the value of PAM_USER_PROMPT is used for prompting. If the value of
       PAM_USER_PROMPT is  NULL, the following default prompt is used:

	 Please enter user name:

       After the user name is gathered by the conversation function, pam_set_item() is called to set the value of  PAM_USER. By convention, appli-
       cations	that  need to prompt for a user name should  call pam_set_item() and set the value of PAM_USER_PROMPT before calling pam_authenti-
       cate(). The service module's pam_sm_authenticate() function will then call pam_get_user() to prompt for the user name.

       Note that certain  PAM service modules, such as a smart card module, may override the value of	PAM_USER_PROMPT  and  pass  in	their  own
       prompt.	Applications  that  call  pam_authenticate() multiple times should set the value of  PAM_USER to  NULL with  pam_set_item() before
       calling pam_authenticate(), if they want the user to be prompted  for  a  new  user  name  each	time.  The  value  of  user  retrieved	by
       pam_get_user() should not be modified or freed.	The item will be released by pam_end().

RETURN VALUES

       Upon  success, pam_get_user() returns  PAM_SUCCESS; otherwise it returns an error code. Refer to pam(3PAM) for information on error related
       return values.

ATTRIBUTES

       See attributes(5) for description of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     | Stable			   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |MT-Safe with exceptions	   |
       +-----------------------------+-----------------------------+

SEE ALSO

       pam(3PAM),  pam_authenticate(3PAM),  pam_end(3PAM),  pam_get_item(3PAM),   pam_set_item(3PAM),	pam_sm(3PAM),	pam_sm_authenticate(3PAM),
       pam_start(3PAM), attributes(5)

NOTES

       The interfaces in  libpam are MT-Safe only if each thread within the multithreaded application uses its own PAM handle.

SunOS 5.11							    13 Oct 1998 						pam_get_user(3PAM)

pam_authenticate(3PAM)					       PAM Library Functions					    pam_authenticate(3PAM)

NAME

       pam_authenticate - perform authentication within the PAM framework

SYNOPSIS

       cc [ flag ... ] file ... -lpam [ library ... ]
       #include <security/pam_appl.h>

       int pam_authenticate(pam_handle_t *pamh, int flags);

DESCRIPTION

       The  pam_authenticate()	function  is  called to authenticate the current user. The user is usually required to enter a password or similar
       authentication token depending upon the authentication service configured within the system. The user in question should have  been  speci-
       fied by a prior call to pam_start() or pam_set_item().

       The following flags may be set in the flags field:

       PAM_SILENT		    Authentication service should not generate any messages.

       PAM_DISALLOW_NULL_AUTHTOK    The authentication service should return  PAM_AUTH_ERR if the user has a null authentication token.

RETURN VALUES

       Upon  successful completion,  PAM_SUCCESS is returned.  In addition to the error return values described in pam(3PAM), the following values
       may be returned:

       PAM_AUTH_ERR		Authentication failure.

       PAM_CRED_INSUFFICIENT	Cannot access authentication data due to insufficient credentials.

       PAM_AUTHINFO_UNAVAIL	Underlying authentication service cannot retrieve authentication information.

       PAM_USER_UNKNOWN 	User not known to the underlying authentication module.

       PAM_MAXTRIES		An authentication service has maintained a retry count which has  been	reached.  No  further  retries	should	be
				attempted.

ATTRIBUTES

       See attributes(5) for description of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     | Stable			   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |MT-Safe with exceptions	   |
       +-----------------------------+-----------------------------+

SEE ALSO

       pam(3PAM), pam_open_session(3PAM), pam_set_item(3PAM), pam_setcred(3PAM), pam_start(3PAM), libpam(3LIB), attributes(5)

NOTES

       In  the	case  of  authentication  failures  due to an incorrect username or password, it is the responsibility of the application to retry
       pam_authenticate() and to maintain the retry count. An authentication service module may implement an internal retry count  and	return	an
       error PAM_MAXTRIES if the module does not want the application to retry.

       If  the	 PAM  framework  cannot load the authentication module, then it will return  PAM_ABORT. This indicates a serious failure, and  the
       application should not attempt to retry the authentication.

       For security reasons, the location of authentication failures is hidden from the user.	 Thus,	if  several  authentication  services  are
       stacked and a single service fails, pam_authenticate() requires that the user re-authenticate each of the services.

       A  null	authentication	token in the authentication database will result in successful authentication unless PAM_DISALLOW_NULL_AUTHTOK was
       specified. In such cases, there will be no prompt to the user to enter an authentication token.

       The interfaces in  libpam are MT-Safe only if each thread within the multithreaded application uses its own  PAM handle.

SunOS 5.11							    27 Jan 2005 					    pam_authenticate(3PAM)