pam_sm_chauthtok Subroutine

Purpose

PAM module-specific implementation of pam_chauthtok().

Library

PAM Library (libpam.a)

Syntax

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

int pam_sm_chauthtok (PAMHandle, Flags, Argc, Argv)
pam_handle_t *PAMHandle;
int Flags;
int Argc;
const char **Argv;

Description

When an application invokes pam_chauthtok(), the PAM Framework calls pam_sm_chauthtok for each module in the password module stack. The pam_sm_chauthtok module interface is intended to change the user's password or authentication token. Before any password is changed, pam_sm_chauthtok performs preliminary tests to ensure necessary hosts and information, depending on the password service, are there. If PAM_PRELIM_CHECK is specified, only these preliminary checks are done. If successful, the authentication token is ready to be changed. If the PAM_UPDATE_AUTHTOK flag is passed in, pam_sm_chauthtok should take the next step and change the user's authentication token. If the PAM_CHANGE_EXPIRED_AUTHTOK flag is set, the module should check the authentication token for aging and expiration. If the user's authentication token is aged or expired, the module should store that information by passing it to pam_set_data(). Otherwise, the module should exit and return PAM_IGNORE. Required information is obtained through the PAM handle or by prompting the user by way of PAM_CONV.

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 are used to set pam_acct_mgmt options. The recognized flags are: 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. PAM_PRELIM_CHECK* Only perform preliminary checks to see if the password can be changed, but do not change it. PAM_UPDATE_AUTHTOK* Perform all necessary checks, and if possible, change the user's password/authentication token. * PAM_PRELIM_CHECK and PAM_UPDATE_AUTHTOK are mutually exclusive.
Argc	The number of module options defined.
Argv	The module options. These options are module-dependent. Any modules receiving invalid options should ignore them.

Return Values

Upon successful completion, pam_sm_chauthtok returns PAM_SUCCESS. 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.