From d4ab77b35c3c5ee8265f328d44a750905b053225 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dag-Erling=20Sm=C3=B8rgrav?= Date: Sun, 17 Mar 2013 19:26:07 +0000 Subject: [PATCH] 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 | 49 ++++++++++++++++++++++++++++-------- lib/libpam/pam_get_user.c | 23 ++++++++++++----- 2 files changed, 56 insertions(+), 16 deletions(-) diff --git a/lib/libpam/pam_get_authtok.c b/lib/libpam/pam_get_authtok.c index ee332d8..584a52e 100644 --- a/lib/libpam/pam_get_authtok.c +++ b/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, - * 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: * @@ -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 - * 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 * 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 */ diff --git a/lib/libpam/pam_get_user.c b/lib/libpam/pam_get_user.c index c12857f..54b3ecf 100644 --- a/lib/libpam/pam_get_user.c +++ b/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 - * 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 */