Technical Reference: Base Operating System and Extensions, Volume 1

chpass Subroutine

Purpose

Changes user passwords.

Library

Standard C Library (libc.a)

Thread Safe Security Library (libs_r.a)

Syntax

int chpass (UserName,  Response,  Reenter,  Message)
char *UserName;
char *Response;
int *Reenter;
char **Message;

Description

The chpass subroutine maintains the requirements that the user must meet to change a password. This subroutine is the basic building block for changing passwords and handles password changes for local, NIS, and DCE user passwords.

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 (zero) and is changing a local user, or if the user has no current password. The chpass subroutine does not prompt a user with root authority for an old password. 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. Once the Reenter parameter is 0, the return code signals whether the password change completed or failed.

The chpass 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 chpass subroutine determines the administration domain to use during password changes. It determines if the user is defined locally, defined in Network Information Service (NIS), or defined in Distributed Computing Environment (DCE). Password changes occur only in these domains. System administrators may override this convention with the registry value in the /etc/security/user file. If the registry value is defined, the password change can only occur in the specified domain. System administrators can use this registry value if the user is administered on a remote machine that periodically goes down. If the user is allowed to log in through some other authentication method while the server is down, password changes remain to follow only the primary server.

The chpass subroutine allows the user to change passwords in two ways. For normal (non-administrative) password changes, the user must supply the old password, either on the first call to the chpass subroutine or in response to the first message from chpass. If the user is root, 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 chpass 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 need do not need to be complied with, the chpass subroutine returns a null challenge.

Parameters

UserName	Specifies the user's name whose password is to be changed.
Response	Specifies a character string containing the user's response to the last prompt.
Reenter	Points to a Boolean value used to signal whether chpass subroutine has completed processing. If the Reenter parameter is a nonzero value, the chpass subroutine expects the user to satisfy the prompt message provided by the Message parameter. If the Reenter parameter is 0, the chpass subroutine has completed processing.
Message	Points to a pointer that the chpass subroutine allocates memory for and fills in. This replacement string is then suitable for printing and issues challenge messages (if the Reenter parameter is a nonzero value). The string can also issue informational messages such as why the user failed to change the password (if the Reenter parameter is 0). The calling application is responsible for freeing this memory.

Return Values

Upon successful completion, the chpass subroutine returns a value of 0. If the chpass subroutine is unsuccessful, it returns the following values:

-1	Indicates the call failed in the thread safe library libs_r.a. ERRNO will indicate the failure code.
1	Indicates that the password change was unsuccessful and the user should attempt again. This return value occurs if a password restriction is not met, such as if the password is not long enough.
2	Indicates that the password change was unsuccessful and the user should not attempt again. This return value occurs if the user enters an incorrect old password or if the network is down (the password change cannot occur).

Error Codes

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

ENOENT	Indicates that the user cannot be found.
ESAD	Indicates that the user did not meet the criteria to change the password.
EPERM	Indicates that the user did not have permission to change the password.
EINVAL	Indicates that the parameters are not valid.
ENOMEM	Indicates that memory allocation (malloc) failed.

Related Information

The authenticate (authenticate Subroutine) subroutine.