chpassx Subroutine

Purpose

Changes multiple method passwords.

Library

Standard C Library (libc.a)

Thread Safe Security Library (libs_r.a)

Syntax

Description

The chpassx subroutine maintains the requirements that the user must meet to change a password. This subroutine is the basic building block for changing passwords, and it handles password changes for local, NIS, and loadable authentication module user passwords. It uses information provided by the authenticatex and passwdexpiredx subroutines to indicate which passwords were used when a user authenticated and whether or not those passwords are expired.

The Message parameter provides a series of messages asking for old and new passwords, or providing informational messages, such as the reason for a password change failing. The first Message prompt is a prompt for the old password. This parameter does not prompt for the old password if the user has a real user ID of 0 and is changing a local user, or if the user has no current password. The chpassx subroutine does not prompt a user with root authority for an old password when only a local password is being changed. It informs the program that no message was sent and that it should invoke chpass again. If the user satisfies the first Message parameter's prompt, the system prompts the user to enter the new password. Each message is contained in the Message parameter and is displayed to the user. The Response parameter returns the user's response to the chpass subroutine.

The Reenter parameter remains a nonzero value until the user satisfies all of the prompt messages or until the user incorrectly responds to a prompt message. When the Reenter parameter is 0, the return code signals whether the password change completed or failed. The calling application must initialize the Reenter parameter to 0 before the first call to the chpassx subroutine and the application cannot modify the Reenter parameter until the sequence of chpassx subroutine calls has completed.

The authenticatex subroutine ascertains the authentication domains the user can attempt. The subroutine uses the SYSTEM attribute for the user. Each token that is displayed in the SYSTEM line corresponds to a method that can be dynamically loaded and processed. Likewise, the system can provide multiple or alternate authentication paths.

The State parameter contains information from an earlier call to the authenticatex or passwdexpirex subroutines. That information indicates which administration domains were used when the user was authenticated and which passwords have expired and can be changed by the user. The State parameter must be initialized to null when the chpassx subroutine is not being called after an earlier call to the authenticatex or passwdexpiredx subroutines, or if the calling program does not wish to use the information from an earlier call.

The chpassx subroutine maintains internal state information concerning the next prompt message to present to the user. If the calling program supplies a different user name before all prompt messages are complete for the user, the internal state information is reset and prompt messages begin again.

The chpassx subroutine determines the administration domain to use during password changes. It determines if the user is defined locally, defined in Network Information Service (NIS), defined in Distributed Computing Environment (DCE), or defined in another administrative domain supported by a loadable authentication module. Password changes use the user's SYSTEM attribute and information in the State parameter. When the State parameter includes information from an earlier call to the authenticatex subroutine, only the administrative domains that were used for authentication are changed. When the State parameter includes information from an earlier call to the passwdexpiredx subroutine, only the administrative domains that have expired passwords are changed. The State parameter can contain information from calls to both authenticatex and passwdexpiredx, in which case passwords that were used for authentication are changed, even if they are not expired, so that passwords remain synchronized between administrative domains.

The chpassx subroutine allows the user to change passwords in two ways. For normal (nonadministrative) password changes, the user must supply the old password, either on the first call to the chpassx subroutine or in response to the first message from chpassx. If the user is root (with a real user ID of 0), local administrative password changes are handled by supplying a null pointer for the Response parameter during the initial call.

Users that are not administered locally are always queried for their old password.

The chpassx subroutine is always in one of three states: entering the old password, entering the new password, or entering the new password again. If any of these states do not need to be complied with, the chpassx subroutine returns a null challenge.

Parameters

Return Values

Upon successful completion, the chpassx subroutine returns a value of 0. If this subroutine fails, it returns the following values:

Error Codes

The chpassx subroutine is unsuccessful if one of the following values is true: