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

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
PAM_GET_AUTHTOK(3)     FreeBSD Library Functions Manual	    PAM_GET_AUTHTOK(3)

NAME
     pam_get_authtok --	retrieve authentication	token

LIBRARY
     Pluggable Authentication Module Library (libpam, -lpam)

SYNOPSIS
     #include <sys/types.h>
     #include <security/pam_appl.h>

     int
     pam_get_authtok(pam_handle_t *pamh, int item, const char **authtok,
	 const char *prompt);

DESCRIPTION
     The pam_get_authtok() function either prompts the user for	an authentica-
     tion token	or retrieves a cached authentication token, depending on cir-
     cumstances.  Either way, a	pointer	to the authentication token is stored
     in	the location pointed to	by the authtok argument, and the corresponding
     PAM item is updated.

     The item argument must have one of	the following values:

     PAM_AUTHTOK	 Returns the current authentication token, or the new
			 token when changing authentication tokens.

     PAM_OLDAUTHTOK	 Returns the previous authentication token when	chang-
			 ing authentication tokens.

     The prompt	argument specifies a prompt to use if no token is cached.  If
     it	is NULL, the PAM_AUTHTOK_PROMPT	or PAM_OLDAUTHTOK_PROMPT item, as
     appropriate, will be used.	 If that item is also NULL, a hardcoded
     default prompt will be used.  Additionally, when pam_get_authtok()	is
     called from a service module, the prompt may be affected by module
     options as	described below.  The prompt is	then expanded using
     openpam_subst(3) before it	is passed to the conversation function.

     If	item is	set to PAM_AUTHTOK and there is	a non-null PAM_OLDAUTHTOK
     item, pam_get_authtok() will ask the user to confirm the new token	by
     retyping it.  If there is a mismatch, pam_get_authtok() will return
     PAM_TRY_AGAIN.

MODULE OPTIONS
     When called by a service module, pam_get_authtok()	will recognize the
     following module options:

     authtok_prompt	 Prompt	to use when item is set	to PAM_AUTHTOK.	 This
			 option	overrides both the prompt argument and the
			 PAM_AUTHTOK_PROMPT item.

     echo_pass		 If the	application's conversation function allows it,
			 this lets the user see	what they are typing.  This
			 should	only be	used for non-reusable authentication
			 tokens.

     oldauthtok_prompt	 Prompt	to use when item is set	to PAM_OLDAUTHTOK.
			 This option overrides both the	prompt argument	and
			 the PAM_OLDAUTHTOK_PROMPT item.

     try_first_pass	 If the	requested item is non-null, return it without
			 prompting the user.  Typically, the service module
			 will verify the token,	and if it does not match,
			 clear the item	before calling pam_get_authtok() a
			 second	time.

     use_first_pass	 Do not	prompt the user	at all;	just return the	cached
			 value,	or PAM_AUTH_ERR	if there is none.

RETURN VALUES
     The pam_get_authtok() function returns one	of the following values:

     [PAM_BUF_ERR]	 Memory	buffer error.

     [PAM_CONV_ERR]	 Conversation failure.

     [PAM_SYSTEM_ERR]	 System	error.

     [PAM_TRY_AGAIN]	 Try again.

SEE ALSO
     openpam_get_option(3), openpam_subst(3), pam(3), pam_conv(3),
     pam_get_item(3), pam_get_user(3), pam_strerror(3)

STANDARDS
     The pam_get_authtok() function is an OpenPAM extension.

AUTHORS
     The pam_get_authtok() function and	this manual page were developed	for
     the FreeBSD Project by ThinkSec AS	and Network Associates Laboratories,
     the Security Research Division of Network Associates, Inc.	under
     DARPA/SPAWAR contract N66001-01-C-8035 (``CBOSS''), as part of the	DARPA
     CHATS research program.

     The OpenPAM library is maintained by Dag-Erling Smorgrav <des@des.no>.

FreeBSD	9.3		       September 7, 2013		   FreeBSD 9.3

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | MODULE OPTIONS | RETURN VALUES | SEE ALSO | STANDARDS | AUTHORS

Want to link to this manual page? Use this URL:
<http://www.freebsd.org/cgi/man.cgi?query=pam_get_authtok&sektion=3&manpath=FreeBSD+10.0-RELEASE>

home | help