VERIFY PASSWORD

Verify that a password matches the password recorded by an external security manager.

VERIFY PASSWORD

Conditions: INVREQ, NOTAUTH, USERIDERR

This command is threadsafe.

Description

Use the VERIFY PASSWORD command to check that a password matches the password recorded by an external security manager for a user ID. The command returns the values recorded by the external security manager for the password. This process is called password verification. If your system uses password phrases in addition to or instead of standard passwords, use the VERIFY PHRASE command instead of the VERIFY PASSWORD command.

Attention: To ensure that passwords are not revealed in system or transaction dumps, clear the password or password phrase fields on the EXEC CICS® commands that have a password or password phrase option as soon as possible after use.

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. For example, a password verification request cannot identify the following problems:

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 the external security manager. 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 EXEC CICS 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.

If you specify the system initialization parameter SECVFYFREQ=USRDELAY for the CICS region, CICS enforces a full verification request at least once a day for each user ID that is used to log on to the CICS region. The full verification request using the RACROUTE REQUEST=VERIFY macro makes RACF® record the date and time of last access for the user ID, and write user statistics. The behavior of your applications is the same whether or not you specify the SECVFYFREQ system initialization parameter. CICS checks the user ID at user login and replaces the password verification request with a full verification request when necessary.

Because the full verification request has a higher processor cost and response time than password verification, you might notice a slight performance impact when you specify the SECVFYFREQ system initialization parameter. The extent of the performance impact depends on your setting for the USRDELAY system initialization parameter for the CICS region. When you specify SECVFYFREQ, CICS makes a full verification request for a user ID when the user logs on after the USRDELAY interval has expired. CICS also applies a maximum limit of one day between full verification requests at user login. If your USRDELAY parameter is set to less than 1440 minutes (1 day), a full verification request takes place at user login more frequently than once a day.

CICS also issues a full verification if an incorrect password is entered, and in the next successful request. In other cases, the VERIFY PASSWORD command uses a fastpath method to verify the password. For details of the SAF interfaces used, see CICS security control points.

Note: In the CHANGETIME, LASTUSETIME, and EXPIRYTIME options, the time value returned is in the same format as the ASKTIME command, that is, in ABSTIME units. For more information about the ABSTIME format, see ASKTIME. The data can be reformatted as a date and time, in a format specified by the caller, by using the FORMATTIME command.

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.

DAYSLEFT(data-area)

Returns the number of days from now until the password expires, in a halfword binary field. If the password is non-expiring, -1 is returned.

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.

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.

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 password, 8 characters, that you want the external security manager 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 user ID, 8 characters, of the user whose password is to be checked.

The user ID supplied is converted to uppercase.

Conditions

16 INVREQ

RESP2 values:

13: There is an unknown return code in ESMRESP from the external security manager.
18: The CICS external security manager interface is not initialized.
29: The external security manager 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.

ESM RESP values:

24: The RACROUTE REQUEST=VERIFY(X) was failed by an ICHRIX01 installation exit routine.

Default action: terminate the task abnormally.

69 USERIDERR

RESP2 values:

8: The user ID is not known to the external security manager.

Default action: terminate the task abnormally.