VERIFY TOKEN

Description

Use the VERIFY TOKEN command to verify that a Kerberos token is valid, as determined by an external security manager. The command optionally returns the user ID of a Kerberos principal that is associated with the token.

The VERIFY TOKEN command uses the z/OS® Security Server to verify that the token is a valid Kerberos token and that it can be used by the CICS® region. If ISUSERID is specified, the user ID of the Kerberos principal for the token is obtained.

The VERIFY TOKEN command does not depend upon the principal facility. Therefore, it can be issued in non-terminal environments, for example to provide authentication for web services.

If the external security manager is RACF®, the CICS region in which the command is run must be authorized by RACF so that the Kerberos principal for the token can be obtained. For more information, see Configuring RACF for Kerberos. This RACF authorization is required whether or not ISUSERID is specified.

For more information about a security failure of this command, see the error messages that are written to destination CSCS.

Options

DATATYPE

Specifies the type of data in the token. CVDA values are as follows:

BIT

Bit data. This is the default value.

BASE64

Base64 encoded character data. The acceptable characters are A-Z a-z 0-9 + / =

If your character data is not in a US EBCDIC compatible character CCSID you must convert it. You can use the CONTAINER API to do the conversion.

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 that are 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 that are returned by this command in addition to checking the ESMRESP and ESMREASON values.

ISUSERID(data-area)

Returns an 8-byte user ID of a Kerberos principal that is associated with the token.

TOKEN(data-area)

A token that has been obtained from a Security Token Service (STS).

TOKENLEN(data-value)

The length of the token as a fullword binary value.

TOKENTYPE(cvda)

Indicates the type of token.

KERBEROS

The token is a Kerberos token.

Conditions

16 INVREQ

RESP2 values are as follows:

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.

31

A CVDA value other than KERBEROS was specified for TOKENTYPE.

32

A CVDA value other than BASE64 or BIT was specified for DATATYPE.

36

A data-type of BASE64 was specified, but TOKEN does not contain BASE64 data.

40

The key distribution center is not started or is terminating.

41

The key distribution center is not responding.

47

The external security manager does not have a user ID defined for the Kerberos principal that is associated with the token.

50

The data specified in TOKEN is not a Kerberos token

Default action: terminate the task abnormally.

22 LENGERR

RESP2 values are as follows:

45

The length of the Kerberos token exceeds the maximum value of 65535.

70 NOTAUTH

RESP2 values are as follows:

20

The external security manager does not authorize the request to verify the token. See the error messages written to destination CSCS.

42

A Kerberos request cannot be completed because the associated ticket has expired.

43

The authenticator has expired.

Default action: terminate the task abnormally.