VERIFY PASSWORD

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

Read syntax diagramSkip visual syntax diagram
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.

Start of changeThe 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.End of change

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.

Start of changeThe 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.End of change

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.