Allow an application to check that a password matches the password
recorded by an external security manager.

VERIFY PASSWORD
>>-VERIFY PASSWORD(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, NOTAUTH, USERIDERR
Description
The VERIFY PASSWORD command allows
an application to check that a password matches the password recorded by an
external security manager (ESM) for a userid, and return values recorded by
the external security manager for the password.
Unlike the SIGNON command,
VERIFY PASSWORD does not depend upon the principal facility, so it can be
issued when the facility is an APPC session.
When the external security
manager is RACF®,
the CHANGETIME and EXPIRYTIME outputs always show as midnight.
If a
VERIFY PASSWORD request is successful, you should not infer that a signon
would also be successful. The userid might not be able to sign on in the CICS
region, for example, because:
- The userid might not be authorized to access the CICS address space (identified
by the APPLID).
- The userid might not be authorized to use the terminal at which the user
is signing on (identified by the TERMINAL class).
Attention: You should clear the password fields on the
EXEC CICS commands that have a password option as soon as possible after use.
This is to ensure that passwords are not revealed in system or transaction
dumps.
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. ABSTIME is the time, in packed decimal, since 00:00 on 1
January 1900 (in milliseconds rounded to the nearest hundredth of a second).
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, in a halfword binary field, until the password
expires. 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 ESM 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.
- 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 userid 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 userid. The other data is not returned if the password
is not valid.
- USERID(data-value)
- specifies
the userid, 8 characters, of the user whose password is to be checked.
If a user has a never-expiring password that was established
with the RACF PASSWORD USER(userid) NOINTERVAL command, the outputs DAYSLEFT
and EXPIRYTIME have little meaning and are shown as -1.
Conditions
- 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 userid field contains a blank character in an invalid position.
Default action: terminate the task abnormally.
- NOTAUTH
- RESP2
values:
- 2
- The supplied password is wrong. If the external security manager is RACF,
the revoke count maintained by RACF is incremented.
- 3
- A new password is required.
- 19
- The user has been revoked.
- 20
- The user's connection to their default group has been revoked.
Default action: terminate the task abnormally.
- USERIDERR
- RESP2
values:
- 8
- The USERID is not known to the external security manager.
Default action: terminate the task abnormally.