pam_chauthtok Subroutine

Edit online

Purpose

Changes the user's authentication token (typically passwords).

Library

PAM Library (libpam.a)

Syntax

#include <security/pam_appl.h>

int pam_chauthtok (PAMHandle, Flags)
pam_handle_t *PAMHandle;
int Flags;

Description

The pam_chauthtok subroutine changes a user's authentication token through the PAM framework. Prior to changing the password, the subroutine performs preliminary tests to ensure that necessary hosts and information, depending on the password service, are there. If any of these tests fail, PAM_TRY_AGAIN is returned. To request information from the user, pam_chauthtok can use the conversation function that is defined in the PAM handle, PAMHandle. After the subroutine is finished, the values of PAM_AUTHTOK and PAM_OLDAUTHTOK are cleared in the handle for added security.

Parameters

Item Description
PAMhandle The PAM handle representing the current user authentication session. This handle is obtained by a call to pam_start().
Flags The Flags argument can be a logically OR'd combination of the following:
  • PAM_SILENT
    • No messages should be displayed
  • PAM_CHANGE_EXPIRED_AUTHTOK
    • Only expired passwords should be changed. If this flag is not included, all users using the related password service are forced to update their passwords. This is typically used by a login application after determining password expiration. It should not generally be used by applications dedicated to changing passwords.

Return Values

Upon successful completion, pam_chauthtok returns PAM_SUCCESS and the authentication token of the user, as defined for a given password service, is changed. If the routine fails, a different error is returned, depending on the actual error.

Error Codes

Item Description
PAM_AUTHTOK_ERR A failure occurred while updating the authentication token.
PAM_TRY_AGAIN Preliminary checks for changing the password have failed. Try again later.
PAM_AUTHTOK_RECOVERY_ERR An error occurred while trying to recover the authentication information.
PAM_AUTHTOK_LOCK_BUSY Cannot get the authentication token lock. Try again later.
PAM_AUTHTOK_DISABLE_AGING Authentication token aging checks are disabled and were not performed.
PAM_USER_UNKNOWN The user is not known.
PAM_OPEN_ERR One of the PAM authentication modules could not be loaded.
PAM_SYMBOL_ERR A necessary item is not available to a PAM module.
PAM_SERVICE_ERR An error occurred in a PAM module.
PAM_SYSTEM_ERR A system error occurred.
PAM_BUF_ERR A memory error occurred.
PAM_CONV_ERR A conversation error occurred.
PAM_PERM_DENIED Access permission was denied to the user.