VERIFY TOKEN

Verify that a Kerberos token is valid, as determined by an external security manager, and optionally allow the caller to extract the RACF® user ID that is associated with the principal in the Kerberos token.

VERIFY TOKEN

Conditions: INVREQ, LENGERR, NOTAUTH

This command is threadsafe.

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. If the Kerberos token indicates mutual authentication is in use, the command returns a Kerberos output 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 ISUSERID is specified.

If ENCRYPTKEY is specified, TOKEN must be a Kerberos token that is obtained from a Security Token Service that supports message confidentiality.

Note: When ENCRYPTKEY is specified, an external security manager such as RACF is called by using the z/OS Security Server RACF Callable Services > R_GenSec function code 2 GSS-API > Accept a GSS-API security context. This R_Gensec subfunction can be called once for a particular Kerberos token. As a result the VERIFY TOKEN command with the ENCRYPTKEY option can be called once for a particular Kerberos token.

If TOKEN is a Kerberos token that indicates mutual authentication is in use, OUTTOKEN and OUTTOKENLEN options must be specified. In this case, OUTTOKEN returns an output token that is obtained from an external security manager such as z/OS Security Server, and OUTTOKENLEN returns the length of the output token. The calling program should return the output token to the system that supplied the Kerberos token, to allow authentication of the CICS region.

If TOKEN is a Kerberos token that does not indicate mutual authentication is in use, and if OUTTOKEN and OUTTOKENLEN are specified, the values returned in these options are zero.

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 and OUTTOKEN options. 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.

ENCRYPTKEY(data-area)

This is the 4-byte token to be used to encrypt a returned PassTicket.

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.

If the external security manager is RACF, and ENCRYPTKEY is used, the possible values are the RACF reason codes that are supplied by the z/OS Security Server RACF Callable Services > R_GenSec function code 2 GSS-API > Accept a GSS-API security context. See GSS-API Subfunction codes in z/OS Security Server RACF Callable Services. For an explanation of a reason code, see R_GenSec Return and reason codes in z/OS Security Server RACF Callable Services and Status codes in z/OS Integrated Security Services Network Authentication Service Administration.

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.

ISUSERID(data-area)

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

OUTTOKEN(ptr-ref)

Returns the address in 31-bit user-key storage of the output token that is obtained from an external security manager.

OUTTOKENLEN(data-area)

Returns the length of an output token, in a fullword binary field with a maximum value of 1024.

TOKEN(data-area)

A token that is 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 issues 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 that is specified in TOKEN is not a Kerberos token.
51: The Kerberos token does not support message confidentiality.
52: The Kerberos token indicates mutual authentication is in use, but OUTTOKEN and OUTTOKENLEN have not been specified on the command.
53: This CICS region is not configured to support Kerberos. To enable Kerberos support, specify the SIT parameter KERBEROSUSER with the user id associated with the service principal.

22 LENGERR

RESP2 values are as follows:

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

Default action: terminate the task abnormally.

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 that are written to destination CSCS.
42: A Kerberos request cannot be completed because the associated ticket expired.
43: The authenticator expired.

Default action: terminate the task abnormally.