VERIFY PASSWORD
Verify that a password matches the password recorded by RACF®.
Description
Use the VERIFY PASSWORD command to check that a password matches the password recorded by RACF for a user ID. The command returns the values recorded by RACF for the password. This process is called password verification. If your system uses passphrases in addition to or instead of standard passwords, use the VERIFY PHRASE command.
When this command is issued by a transaction running under CEDF, the password or passphrase (and new password or passphrase, where applicable) is blanked out.
If a VERIFY PASSWORD request is successful, do not infer that the user ID could also be used to sign on in the CICS® region with the EXEC CICS SIGNON command.
The GROUPID option identifies a group that is to be included as part of the verification of the password. When the GROUPID option is used, if the VERIFY PASSWORD request is successful, do not infer that the group ID can also be used to sign on to the CICS region with the EXEC CICS SIGNON command.
- The user ID's connections to groups have been revoked.
- The user ID is not authorized to access the CICS address space (identified by the APPLID).
- The user ID is not authorized to use the terminal at which the user is signing on (identified by the TERMINAL class).
If you supply an incorrect password on the VERIFY PASSWORD request, the invalid attempt count is increased for the user ID. If you supply multiple incorrect passwords on successive VERIFY PASSWORD requests, the user ID may be revoked by RACF. CICS issues message DFHXS1201 when you supply an incorrect password on a VERIFY PASSWORD request. When you supply a correct password following one or more invalid attempts, CICS issues message DFHXS1206, which includes a count of the invalid attempts.
Unlike the SIGNON command, the VERIFY PASSWORD command does not depend upon the principal facility; therefore, it can be issued in non-terminal environments such as web applications.
CICS enforces a full verification request at the first time each day that a user ID is used to log on to the CICS region or is verified through a VERIFY PASSWORD or VERIFY PHRASE command. The full verification request records the date and time of last access for the user ID, and writes user statistics. A full verification is also made if an incorrect password or password phrase is entered, and in the next successful request. In other cases, the command uses a fastpath method to verify the password or password phrase. For details of the SAF interfaces used, see CICS security control points.
Options
- CHANGETIME(data-area)
- Returns
the date and time the password was last changed, in ABSTIME units.
When the external security manager is RACF, the time is shown as midnight.
If the supplied password is successfully verified but has expired or is not set in the external security manager, CHANGETIME has no meaning and is shown as -2.
- DAYSLEFT(data-area)
- Returns the
number of days from now until the password expires, in a halfword binary field.
If a user has a password that does not expire, DAYSLEFT has no meaning and is shown as -1.
If the supplied password is successfully verified but has expired or is not set in the external security manager, DAYSLEFT has no meaning and is shown as -2.
- ESMREASON(data-area)
- Returns the
reason code, in a fullword binary field, that CICS receives
from the external security manager.
If the external security manager is RACF, this field is the RACF reason code.
The external security manager does not always return response and reason codes to CICS. Make sure that you check the EIBRESP and EIBRESP2 values returned by this command in addition to checking the ESMRESP and ESMREASON values.
- ESMRESP(data-area)
- Returns the
response code, in a fullword binary field, that CICS receives
from the external security manager.
If the external security manager is RACF, this field is the RACF return code.
The external security manager does not always return response and reason codes to CICS. Make sure that you check the EIBRESP and EIBRESP2 values returned by this command in addition to checking the ESMRESP and ESMREASON values.
- EXPIRYTIME(data-area)
- Returns
the date and time the password will expire, in ABSTIME units.
When the external security manager is RACF, the time is shown as midnight.
If a user has a password that does not expire, EXPIRYTIME has no meaning and is shown as -1.
If the supplied password is successfully verified but has expired or is not set in the external security manager, DAYSLEFT has no meaning and is shown as -2.
- GROUPID(data-value)
- Specifies the 8-character group ID of the user whose password is to be checked.
- INVALIDCOUNT(data-area)
- Returns the number of times, in a halfword binary field, that an invalid password was entered for this user.
- LASTUSETIME(data-area)
- Returns the data and time this user ID was last accessed, in ABSTIME units.
- PASSWORD(data-value)
- Specifies the 8-character password that you want RACF to check for the specified user ID. The other data is not returned if the password is not valid.
If the ESM does not allow mixed case passwords, the password is converted to uppercase.
- USERID(data-value)
- Specifies the
8-character user ID of the user whose password is to be checked.
The user ID supplied is converted to uppercase.
Conditions
- 16 INVREQ
- RESP2
values:
- 13
- The value that is returned by RACF in ESMRESP is not classified by CICS. See the ESM documentation for an explanation of the ESMRESP and ESMREASON values.
- 18
- The CICS external security manager (ESM) interface is not initialized.
- 29
- The external security manager (ESM) is not responding.
- 32
- The user ID field contains a blank character in an invalid position.
Default action: terminate the task abnormally.
- 70 NOTAUTH
- RESP2
values:
- 1
- The PASSWORD field is blank.
- 2
- The supplied password is wrong. If the external security manager is RACF, the revoke count maintained by RACF is incremented.
However, if ESM RESP = 24, the revoke count is not incremented.
- 3
- A new password is required.
- 17
- The USERID is not authorized to use the application.
- 19
- The user ID is revoked.
- 20
- The user's connection to their default group has been revoked.
- 23
- The value of GROUPID is not valid with the values of USERID and PASSWORD.
- 69 USERIDERR
- RESP2
values:
- 8
- The user ID is not known to the external security manager.
Default action: terminate the task abnormally.