NAME

pam_sm_chauthtok - service provider implementation for pam_chauthtok

SYNOPSIS

#include <security/pam_appl.h>
#include <security/pam_modules.h>

int pam_sm_chauthtok(
    pam_handle_t    *pamh,
    const int       flags,
    int             argc,
    const char    **argv
);

DESCRIPTION

In response to a call to pam_chauthtok() the PAM framework calls pam_sm_chauthtok() from the modules listed in the PAM configuration. The password management provider supplies the back-end functionality for this interface function.

pam_sm_chauthtok() changes the authentication token associated with a particular user referenced by the authentication handle, pamh.

Upon successful completion of the call, the authentication token of the user will be ready for change or will be changed (depending upon the flag) in accordance with the authentication scheme configured within the system.

It is the responsibility of pam_sm_chauthtok() to determine if the new password meets certain strength requirements. pam_sm_chauthtok() may continue to re-prompt the user (for a limited number of times) using the conversation functions for a new password until the password entered meets the strength requirements.

Before returning, pam_sm_chauthtok() should call pam_get_item() and retrieve both PAM_AUTHTOK and PAM_OLDAUTHTOK. If both are NULL, pam_sm_chauthtok() should set them to the new and old passwords as entered by the user.

Note that the framework invokes the password services twice. The first time the modules are invoked with the flag, PAM_PRELIM_CHECK. During this stage, the password modules should only perform preliminary checks (ping remote name services to see if they are ready for updates, for example). If a password module detects a transient error (remote name service temporarily down, for example) it should return PAM_TRY_AGAIN to the PAM framework, which will immediately return the error back to the application. If all password modules pass the preliminary check, the PAM framework invokes the password services again with the flag, PAM_UPDATE_AUTHTOK. During this stage, each password module should proceed to update the appropriate password. Any error will again be reported back to application.

If a service module receives the flag, PAM_CHANGE_EXPIRED_AUTHTOK, it should check whether the password has aged or expired. If the password has aged or expired, then the service module should proceed to update the password. If the status indicates that the password has not yet aged/expired, then the password module should return PAM_IGNORE.

If a user's password has aged or expired, a PAM account module could save this information as state in the authentication handle, pamh, using pam_set_data(). The related password management module could retrieve this information using pam_get_data() to determine whether or not it should prompt the user to update the password for this particular module.

The arguments for pam_sm_chauthtok() are:

pamh (in)

The PAM authentication handle, obtained from a previous call to pam_start().

flags (in)

The following flag may be passed in to pam_sm_chauthtok():

PAM_SILENT

The password service should not generate any messages.

PAM_CHANGE_EXPIRED_AUTHTOK

The password service should only update those passwords that have aged. If this flag is not passed, the password service should update all passwords.

PAM_PRELIM_CHECK

The password service should only perform preliminary checks. No passwords should be updated.

PAM_UPDATE_AUTHTOK

The password service should update passwords.

Note that PAM_PRELIM_CHECK and PAM_UPDATE_AUTHTOK cannot be set at the same time.

argc (in)

The argc argument represents the number of module options passed in from the PAM configuration.

argv (in)

Specifies the module options, which are interpreted and processed by the password management module. Please refer to the specific module man pages for the various available options.

RETURN VALUE

The following PAM status codes shall be returned:

[PAM_SUCCESS]

Successful completion.

[PAM_AUTHTOK_ERR]

Authentication token manipulation error.

[PAM_AUTHTOK_RECOVERY_ERR]

Old authentication token cannot be retrieved.

[PAM_AUTHTOK_LOCK_BUSY]

The authentication token lock is busy.

[PAM_AUTHTOK_DISABLE_AGING]

Authentication token again disabled.

[PAM_USER_UNKNOWN]

User unknown to password service.

[PAM_TRY_AGAIN]

Preliminary check by password service failed.

[PAM_IGNORE]

Ignore underlying session module regardless of whether the control flag is required, optional or sufficient.

[PAM_PERM_DENIED]

The caller does not possess the required authority.

[PAM_SERVICE_ERR]

Error in service module.

[PAM_SYSTEM_ERR]

System error.

[PAM_BUF_ERR]

Memory buffer error.

[PAM_CONV_ERR]

Conversation error.

[??] Some characters or strings that appear in the printed document are not easily representable using HTML.