Check Password Exit Program
Required Parameter:
1 | Check password exit information | Input | Char(*) |
2 | Return indicator | Output | Char(1) |
QSYSINC Member Name: ECHKPWD1
Exit Point Name: QIBM_QSY_CHK_PASSWRD
Exit Point Format Name: CHKP0100
The Check Password exit program is called when a Create User Profile (CRTUSRPRF) command, Change User Profile (CHGUSRPRF) command, Change Password (CHGPWD) command, or Change Password (QSYCHGPW) API is used to set or change the password associated with a user profile. The exit program is called after the system value based password composition rules have been successfully checked.
Note: The Limit Password Character Positions (QPWDPOSDIF) system value based composition rule is not checked before calling the exit program because the old password value is not available through all of the interfaces that can set or change the password.
The exit program can examine the new password value for conformance with customer unique password composition rules. The exit program returns an indication whether the new password conforms to the customer's password rules. This indication will be used so that the security audit journal can record whether the changed password conforms to the password composition rules. However, the password will be changed regardless of whether the exit program returns an indication that the password does not conform to the customer's password rules.
The exit point supports multiple exit programs. However, additional exit programs will not be called after receiving an indication that the new password does not conform from one of the exit programs. (For information about adding an exit program to an exit point, see the Registration Facility part.)
Any escape message received from an exit program or encountered while trying to call an exit program, will be treated as an indication that the new password does not conform to the customer's password rules.
The specified exit program must exist in the system auxiliary storage pool (ASP) or one of the basic user ASPs at the time it is added to the registration facility. If the program does not exist, the request to add the exit program will be rejected.
The exit program must exist in the system ASP or one of the basic user ASPs at the time the exit point attempts to locate the exit program. If the specified exit program does not exist in the system ASP or one of the basic user ASPs, the condition will be treated as an indication that the new password does not conform to the customer's password rules.
This exit point is very similar to the QIBM_QSY_VLD_PASSWRD exit point. The key differences between these two exit points are:
- This exit point is called after the password has been changed while the QIBM_QSY_VLD_PASSWRD exit is called before the password is changed.
- The returned indicator for this exit program does not affect the password change while the return indicator from the QIBM_QSY_VLD_PASSWRD exit does affect whether the password is changed.
- This exit point is called for passwords set by the CRTUSRPRF and CHGUSRPRF comands. The QIBM_QSY_VLD_PASSWRD exit point, format VLDP0100, is not called for either of these commands. The QIBM_QSY_VLD_PASSWRD exit point, format VLDP0200, is called for both of these commands when the system value QPWDRULES contains the value *ALLCRTCHG.
- This exit point is called for passwords set by the CHGPWD command and the QSYCHGPW API. The QIBM_QSY_VLD_PASSWRD exit point, format VLDP0100, is called for both of these commands. The QIBM_QSY_VLD_PASSWRD exit point, format VLDP0200, is not called for either of these commands.
Note: When running in a system job, subsystem job, or SCPF job the Check Password exit programs are not called.
Authorities and Locks
- User Profile Authority
- *ALLOBJ and *SECADM to add or remove exit programs to the registration facility
Required Parameter
- Check password exit information
- INPUT; CHAR(*)
Information needed by the exit program for notification of a password change. For details, see Format of Check Password Exit Information.
- Return indicator
- OUTPUT; CHAR(1)
Indicates whether the new password conforms to the customer's password rules.
'0' Indicates that the new password conforms to the customer's password rules. '1' Indicates that the new password does not conform to the customer's password rules. Note: Any value other than '0' indicates that the new password does not conform to the customer's password rules.
Format of Check Password Exit Information
The following table shows the structure of the check password exit information for format CHKP0100. For a description of the fields in this format, see Field Descriptions.
Offset | Type | Field | |
---|---|---|---|
Dec | Hex | ||
0 | 0 | CHAR(20) | Exit point name |
20 | 14 | CHAR(8) | Exit point format name |
28 | 1C | BINARY(4) | Password level |
32 | 20 | CHAR(10) | User profile name |
42 | 2A | CHAR(2) | Reserved |
44 | 2C | BINARY(4) | Offset to old password |
48 | 30 | BINARY(4) | Length of old password |
52 | 34 | BINARY(4) | CCSID of old password |
56 | 38 | BINARY(4) | Offset to new password |
60 | 3C | BINARY(4) | Length of new password |
64 | 40 | BINARY(4) | CCSID of new password |
CHAR(*) | Old password | ||
CHAR(*) | New password |
Field Descriptions
CCSID of new password. The CCSID of the new password field. The CCSID value will be 13488.
CCSID of old password. The CCSID of the old password field. The CCSID value will be 13488.
Exit point format name. The format name for the Check Password exit program. The possible format name is:
CHKP0100 | The format name that is used after a user password is changed by the CRTUSRPRF, CHGUSRPRF, CHGPWD command or QSYCHGPW API. |
Exit point name. The name of the exit point that calls the exit program.
Length of new password. The length, in bytes, of the new password field.
Length of old password. The length, in bytes, of the old password field.
The length value will be 12. The old password value is not available in all cases so a value of '*NOPWD' is used. This allows the format of the information passed to the QIBM_QSY_CHK_PASSWRD and QIBM_QSY_VLD_PASSWRD exit programs to be the same.
New password. The new password value.
Offset to new password. The offset from the beginning of the check password exit information to the new password field.
Offset to old password. The offset from the beginning of the check password exit information to the old password field.
Old password. The old password value.
The old password value is not available in all cases so a value of '*NOPWD' is used. This allows the format of the information passed to the QIBM_QSY_CHK_PASSWRD and QIBM_QSY_VLD_PASSWRD exit programs to be the same.
Password level. The password level in effect for the system. See the QPWDLVL system value for a description of the possible values.
User profile name. The name of the user profile whose password is being changed.
API introduced: V5R4
[ Back to top | Security APIs | APIs by category ]