NAME

pam_chauthtok - perform password related functions within the PAM framework

SYNOPSIS

#include <security/pam_appl.h>

int pam_chauthtok (
    pam_handle_t    *pamh,
    int              flags
);

DESCRIPTION

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

pam_chauthtok() performs a preliminary check before attempting to update passwords. This check is performed for each password module in the stack as listed in PAM configuration data. The check may include pinging remote name services to determine if they are available. If pam_chauthtok() returns [PAM_TRY_AGAIN], then the check has failed, and passwords are not updated.

The underlying PAM password modules may use the PAM conversation functions to get relevant information from the user.

Note:

That it is possible that the password update succeeds only in some modules.

For security reasons, pam_chauthtok() clears the PAM_AUTHTOK and PAM_OLDAUTHTOK items in the PAM handle prior to returning to the calling application.

The arguments for pam_chauthtok() are:

pamh (in)

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

flags (in)

Flags may be set to:

PAM_SILENT
Disable messages from the password service.

PAM_CHANGE_EXPIRED_AUTHTOK
Specify that only expired passwords should be changed. If this flag is not passed, all password services should update their passwords.

The flag PAM_CHANGE_EXPIRED_AUTHTOK is typically used by a login application which has determined that the user's password has aged or expired. Before allowing the user to login, the login application may invoke pam_chauthtok() with this flag to allow the user to update the password. Typically applications such as passwd should not use this flag.

RETURN VALUE

The following PAM status codes shall be returned:

[PAM_SUCCESS]

Successful completion.

[PAM_AUTHTOK_ERR]

There has been a failure in updating the authentication token.

[PAM_TRY_AGAIN]

Preliminary check on the password has failed. Try again.

[PAM_AUTHTOK_RECOVERY_ERR]

The authentication information cannot be recovered.

[PAM_AUTHTOK_LOCK_BUSY]

The authentication token lock is busy.

[PAM_AUTHTOK_DISABLE_AGING]

Authentication token aging is disabled.

[PAM_USER_UNKNOWN]

The user is unknown to the password service.

[PAM_PERM_DENIED]

The caller does not possess the required authority.

[PAM_OPEN_ERR]

Failure when dynamically loading a service module.

[PAM_SYMBOL_ERR]

Symbol not found in service module.

[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.