Changeset 670 in openpam for trunk/lib/libpam

Timestamp:

Mar 17, 2013, 7:26:07 PM (8 years ago)

Author:

Dag-Erling Smørgrav

Message:

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

Location:

trunk/lib/libpam

Files:

• pam_get_authtok.c (modified) (3 diffs)
• pam_get_user.c (modified) (2 diffs)

trunk/lib/libpam/pam_get_authtok.c

@@ -169 +169 @@
 
 /**
- * The =pam_get_authtok function returns the cached authentication token,
- * or prompts the user if no token is currently cached.
+ * The =pam_get_authtok function either prompts the user for an
+ * 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:
@@ -187 +189 @@
  * 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
- * passed to the conversation function.
- *
- * If =pam_get_authtok is called from a module and the ;authtok_prompt /
- * ;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.
+ * 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 before it is passed to
+ * the conversation function.
  *
  * If =item is set to =PAM_AUTHTOK and there is a non-null =PAM_OLDAUTHTOK
@@ -200 +199 @@
  * 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
  */

trunk/lib/libpam/pam_get_user.c

@@ -117 +117 @@
  * 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
@@ -123 +124 @@
  * 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
- * passed to the conversation function.
+ * Additionally, when =pam_get_user 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 before it is passed to
+ * the conversation function.
  *
- * If =pam_get_user is called from a module and the ;user_prompt option is
- * set in the policy file, the value of that option takes precedence over
- * both the =prompt argument and the =PAM_USER_PROMPT item.
+ * MODULE OPTIONS
  *
+ * 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
  */