Changes multiple method passwords.
Standard C Library (libc.a)
Thread Safe Security Library (libs_r.a)
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.
| Item | Description |
|---|---|
| Message | Points to a pointer that the chpassx 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. |
| Reenter | Points to an integer value used to signal whether the chpassx subroutine has completed processing. If the Reenter parameter is a nonzero value, the chpassx subroutine expects the user to satisfy the prompt message provided by the Message parameter. If the Reenter parameter is 0, the chpassx subroutine has completed processing. |
| Response | Specifies a character string containing the user's response to the last prompt. |
| State | Points to a pointer that the chpassx subroutine allocates memory for and fills in. The State parameter can also be the result of an earlier call to the authenticatex or passwdexpiredx subroutines. This parameter contains information about each password that has been changed for the user. The calling application is responsible for freeing this memory after the chpassx subroutine has completed. |
| UserName | Specifies the user's name whose password is to be changed. |
Upon successful completion, the chpassx subroutine returns a value of 0. If this subroutine fails, it returns the following values:
| Item | Description |
|---|---|
| -1 | The call failed in the libs_r.a thread safe library. errno indicates the failure code. |
| 1 | The password change was unsuccessful and the user should try again. This return value occurs if a password restriction is not met (for example, the password is not long enough). |
| 2 | The password change was unsuccessful and the user should not try again. This return value occurs if the user enters an incorrect old password or if the network is down (the password change cannot occur). |
The chpassx subroutine is unsuccessful if one of the following values is true:
| Item | Description |
|---|---|
| EINVAL | The parameters are not valid. |
| ENOENT | The user cannot be found. |
| ENOMEM | Memory allocation (malloc) failed. |
| EPERM | The user did not have permission to change the password. |
| ESAD | The user did not meet the criteria to change the password. |