Application Programming Reference

VERIFY PASSWORD

Allows an application to check whether a password matches the password that is recorded for a particular user (possibly by an external authentication manager).

Syntax

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)-'
 
 

Description

The VERIFY PASSWORD command allows an application to check whether a password matches the password that is recorded for a particular user ID (by reference to an external authentication manager, EAM, if configured). It also returns values that are recorded by any external authentication manager for the password.

Note:

Where no external authentication manager (EAM) is used, or the EAM that is used does not support recording some or all the values that are returned about a password, default values are returned as noted in the option descriptions.

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 authentication manager is RACF, the CHANGETIME and EXPIRYTIME outputs always show as midnight.

If a VERIFY PASSWORD request is successful, do not assume that a signon would also be successful. For example, the user ID might be revoked in one or more RACF group connections, or it might not be able to signon in this CICS region.

Attention: Clear the password fields on the EXEC CICS commands that have a password option as soon as possible after use. This action ensures that passwords are not revealed in system or transaction dumps.

Options

CHANGETIME(data-area)

Returns the date and time at which the password was last changed, in ABSTIME units. When the external authentication manager is RACF, the time is shown as midnight (default).

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 (the default) is returned.

ESMREASON(data-area)

Returns the reason code, in a fullword binary field, that CICS receives from the external authentication manager. If the EAM is RACF, this field is the RACF reason code.

ESMRESP(data-area)

Returns the response code, in a fullword binary field, that CICS receives from the external authentication manager. If the external authentication manager is RACF, this field is the RACF return code.

EXPIRYTIME(data-area)

Returns the date and time at which the password will expire, in ABSTIME units. When the external authentication manager is RACF, the time is shown as midnight (default).

INVALIDCOUNT(data-area)

Returns the number of times an invalid password was entered for this user. The default value is zero.

LASTUSETIME(data-area)

Returns the data and time at which this user ID was last accessed, in ABSTIME units. The default value is midnight on January 1st 1970.

PASSWORD(data-value)

Specifies the password, in 8 characters, that you want the external authentication manager to check for the specified user ID. The other data is not returned if the password is not valid.

USERID(data-value)

Specifies the user ID, in 8 characters, of the user whose password is to be checked.

Note:

In the CHANGETIME, LASTUSETIME, and EXPIRYTIME options, the time value that is returned is in the same format as that of the ASKTIME command. It can, therefore, be reformatted as a date and time, in a format that is specified by the caller, by using the FORMATTIME command. 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

An unknown return code exists in ESMRESP from the external authentication manager.

18

The CICS external authentication manager interface is not initialized.

29

The external authentication manager is not responding.

32

The user ID field contains a blank character in an invalid position.

Default action: Terminates the task abnormally.

NOTAUTH

RESP values:

2

The supplied password is wrong. If the external authentication manager is RACF, the revoke count that RACF maintains is incremented.

3

A new password is required.

19

The user ID is revoked.

Default action: Terminates the task abnormally.

USERIDERR

RESP2 values:

8

The user ID is not known to the external authentication manager.

Default action: Terminates the task abnormally.