man/man3pam/pam_chauthtok.3pam

         te
 Copyright (c) 2007, Sun Microsystems, Inc.
 All Rights Reserved
 The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
 You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
 When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
 PAM_CHAUTHTOK 3PAM "Mar 1, 2005"
 NAME
pam_chauthtok - perform password related functions within the PAM framework
 SYNOPSIS

cc [ flag ... ] file ... -lpam [ library ... ]
#include <security/pam_appl.h>

int pam_chauthtok(pam_handle_t *pamh, const int flags);


 DESCRIPTION

The pam_chauthtok() function is called to change the authentication token
associated with a particular user referenced by the authentication handle
pamh.

The following flag may be passed in to pam_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, all password services should update their passwords.


PAM_NO_AUTHTOK_CHECK

The password service should not perform conformance checks on the password
entered.


Upon successful completion of the call, the authentication token of the user
will be changed in accordance with the password service configured in the
system through pam.conf(5).
 RETURN VALUES

Upon successful completion, PAM_SUCCESS is returned. In addition to the
error return values described in pam(3PAM), the following values may be
returned:
PAM_PERM_DENIED

No permission.


PAM_AUTHTOK_ERR

Authentication token manipulation error.


PAM_AUTHTOK_RECOVERY_ERR

Authentication information cannot be recovered.


PAM_AUTHTOK_LOCK_BUSY

Authentication token lock busy.


PAM_AUTHTOK_DISABLE_AGING

Authentication token aging disabled.


PAM_USER_UNKNOWN

User unknown to password service.


PAM_TRY_AGAIN

Preliminary check by password service failed.


 ATTRIBUTES

See attributes(7) for description of the following attributes:


ATTRIBUTE TYPE ATTRIBUTE VALUE
Interface Stability Stable
MT-Level MT-Safe with exceptions


 SEE ALSO

login(1), passwd(1), pam(3PAM), pam_authenticate(3PAM),
pam_start(3PAM), attributes
 NOTES

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(1) should not use this flag.

The pam_chauthtok() functions performs a preliminary check before
attempting to update passwords. This check is performed for each password
module in the stack as listed in pam.conf(5). 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 flag PAM_NO_AUTHTOK_CHECK is typically used by programs that allow an
administrator to bypass various password conformance checks when setting a
password for a user.

The interfaces in libpam are MT-Safe only if each thread within the
multithreaded application uses its own PAM handle.