Document the effect of module options (echo_pass, *_prompt etc)

git-svn-id: svn+ssh://svn.openpam.org/svn/openpam/trunk@670 185d5e19-27fe-0310-9dcf-9bff6b9f3609

lib/libpam/pam_get_authtok.c

@@ -168,10 +168,12 @@ pam_get_authtok(pam_handle_t *pamh,
  */
 
 /**
- * The =pam_get_authtok function returns the cached authentication token,
+ * The =pam_get_authtok function either prompts the user for an
- * or prompts the user if no token is currently cached.
+ * authentication token or retrieves a cached authentication token,
+ * depending on circumstances.
  * Either way, a pointer to the authentication token is stored in the
- * location pointed to by the =authtok argument.
+ * location pointed to by the =authtok argument, and the corresponding PAM
+ * item is updated.
  *
  * The =item argument must have one of the following values:
  *
@@ -186,20 +188,47 @@ pam_get_authtok(pam_handle_t *pamh,
  * 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.
- * Either way, the prompt is expanded using =openpam_subst before it is
+ * Additionally, when =pam_get_authtok is called from a service module,
- * passed to the conversation function.
+ * the prompt may be affected by module options as described below.
- *
+ * The prompt is then expanded using =openpam_subst before it is passed to
- * If =pam_get_authtok is called from a module and the ;authtok_prompt /
+ * the conversation function.
- * ;oldauthtok_prompt option is set in the policy file, the value of that
- * option takes precedence over both the =prompt argument and the
- * =PAM_AUTHTOK_PROMPT / =PAM_OLDAUTHTOK_PROMPT item.
  *
  * 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.
+ *
+ * >pam_conv
  * >pam_get_item
  * >pam_get_user
+ * >openpam_get_option
  * >openpam_subst
  */

lib/libpam/pam_get_user.c

@@ -116,20 +116,31 @@ pam_get_user(pam_handle_t *pamh,
  * If no user was specified, nor set using =pam_set_item, =pam_get_user
  * will prompt for a user name.
  * Either way, a pointer to the user name is stored in the location
- * pointed to by the =user argument.
+ * pointed to by the =user argument, and the corresponding PAM item is
+ * updated.
  *
  * The =prompt argument specifies a prompt to use if no user name is
  * cached.
  * If it is =NULL, the =PAM_USER_PROMPT item will be used.
  * If that item is also =NULL, a hardcoded default prompt will be used.
- * Either way, the prompt is expanded using =openpam_subst before it is
+ * Additionally, when =pam_get_user is called from a service module, the
- * passed to the conversation function.
+ * prompt may be affected by module options as described below.
+ * The prompt is then expanded using =openpam_subst before it is passed to
+ * the conversation function.
  *
- * If =pam_get_user is called from a module and the ;user_prompt option is
+ * MODULE OPTIONS
- * set in the policy file, the value of that option takes precedence over
- * both the =prompt argument and the =PAM_USER_PROMPT item.
  *
+ * When called by a service module, =pam_get_user will recognize the
+ * following module options:
+ *
+ *	;user_prompt:
+ *		Prompt to use when asking for the user name.
+ *		This option overrides both the =prompt argument and the
+ *		=PAM_USER_PROMPT item.
+ *
+ * >pam_conv
  * >pam_get_item
  * >pam_get_authtok
+ * >openpam_get_option
  * >openpam_subst
  */