Verify that a password or password phrase matches the password or password phrase recorded by an external security manager.
VERIFY PHRASE >>-VERIFY PHRASE(data-area)--PHRASELEN(data-value)--------------> >--USERID(data-value)--+-----------------------+----------------> '-CHANGETIME(data-area)-' >--+---------------------+--+----------------------+------------> '-DAYSLEFT(data-area)-' '-ESMREASON(data-area)-' >--+--------------------+--+-----------------------+------------> '-ESMRESP(data-area)-' '-EXPIRYTIME(data-area)-' >--+-------------------------+--+------------------------+----->< '-INVALIDCOUNT(data-area)-' '-LASTUSETIME(data-area)-'
Conditions: INVREQ, LENGERR, NOTAUTH, USERIDERR
This command is threadsafe.
Description
Use the VERIFY PHRASE command to check that a password or password phrase matches the password or password phrase recorded by an external security manager for a user ID. The command returns the values recorded by the external security manager for the password or password phrase. This process is called password verification.
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.
A user ID can have both a standard password and a password phrase. If the length of the phrase as specified by PHRASELEN is between 1 and 8 characters, it is treated as a standard password and the external security manager checks that the PHRASE value matches the password recorded by the external security manager for the user ID. If the length is between 9 and 100 characters, it is treated as a password phrase and the external security manager checks that the PHRASE value matches the password phrase recorded for the user ID.
Although the expiry interval is the same for passwords and password phrases, because they are changed independently, there are separate values for the CHANGETIME and DAYSLEFT options. The values returned for these two parameters depend on whether a valid password or a password phrase is used in the VERIFY PHRASE 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).
Unlike the EXEC CICS SIGNON command, the VERIFY
PHRASE 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=VERIFYX 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.
Options
- CHANGETIME(data-area)
- Returns
the date and time the password or password phrase 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 or password phrase expires, in a halfword binary field. If the password or password phrase does not expire, a value of -1 is returned. If a user has a password or password phrase that does not expire, DAYSLEFT has no meaning and is shown as -1.
- 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 or password phrase that does not expire, EXPIRYTIME has no meaning and is shown as -1.
- INVALIDCOUNT(data-area)
- Returns the number of times, in a halfword binary field, that an invalid password or password phrase was entered for this user.
- LASTUSETIME(data-area)
- Returns the data and time this user ID was last accessed, in ABSTIME units.
- PHRASE(data-area)
- Specifies a 1-
to 8-character password or a 9- to 100-byte password phrase required by the ESM. The other data is
not returned if the phrase is not valid.
If the ESM does not allow mixed case passwords, the 1- to 8-character password is converted to uppercase.
- PHRASELEN(data-value)
- Specifies the length of the password or password phrase as a fullword binary value.
- USERID(data-value)
- Specifies the
user ID associated with the password or password phrase that to be checked.
The user ID supplied is converted to uppercase.
Conditions
- 16 INVREQ
- RESP2
values:
- 13
- The external security manager has issued an unknown return code in ESMRESP.
- 18
- The CICS external security manager interface is not initialized.
- 29
- The external security manager is not responding.
- 32
- The USERID field contains a blank character in an invalid position.
Default action: terminate the task abnormally.
- 22 LENGERR
- RESP2
values:
- 1
- PHRASELEN was out-of-range.
- 70 NOTAUTH
- RESP2
values:
- 2
- The supplied password or password phrase 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 or password phrase is required.
- 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.
