REQUEST ENCRYPTPTKT

Request RACF to generate an encrypted PassTicket.

REQUEST ENCRYPTPTKT

Conditions: NOTAUTH, INVREQ

This command is threadsafe.

Description

The REQUEST ENCRYPTPTKT command requests RACF to generate an encrypted PassTicket. For information about PassTickets, see How it works: PassTickets .

ENCRYPTKEY must contain a value that is returned by a previous VERIFY TOKEN command for the same CICS® task.

Note: When a VERIFY TOKEN command is run with the ENCRYPTKEY option, any previous value of ENCRYPTKEY that was obtained for the same task is no longer valid. It means if a number of VERIFY TOKEN commands are run, it is only an ENCRYPTKEY value from the last one that is valid to use with a REQUEST ENCRYPTPTKT command.

A value in ENCRYPTKEY can be used once to obtain an encrypted PassTicket with a REQUEST ENCRYPTPTKT command. Having run a REQUEST ENCRYPTPTKT command once, if another encrypted PassTicket is required, it is necessary to run a VERIFY TOKEN command again to obtain a new value with the ENCRYPTKEY option. Then, you can run a REQUEST ENCRYPTPTKT command for a second time.

The encrypted PassTicket returned by a REQUEST ENCRYPTPTKT command is intended for decryption by the subsystem that supplied the Kerberos token, and that was used with the VERIFY TOKEN command with ENCRYPTKEY option.

The encrypted PassTicket that RACF generates is for the user ID associated with the task that issues the REQUEST ENCRYPTPTKT command. Use the EXEC CICS ASSIGN command with the USERID option to identify the user ID that is associated with the task. A PassTicket cannot be obtained for the default user ID.

For information about prerequisites for PassTickets, see Implementing PassTickets for secure sign-on.

Options

ENCRYPTPTKT(ptr-ref)

Specifies a data area in which the encrypted PassTicket is returned.

FLENGTH(fullword binary data-area)

Returns the length of the encrypted PassTicket.

ENCRYPTKEY(data-area)

This is the 4-byte token that is obtained from a previous VERIFY TOKEN representing the key to be used to encrypt the PassTicket.

ESMAPPNAME(data-value)

Specifies the eight-character profile name by which the external security manager refers to the application for which the supplied PassTicket is used. For example, if the application is another CICS region, the profile name might be the APPLID of the CICS region. For more information about RACF® profile names and PassTickets, see Using PassTickets in z/OS Security Server RACF Security Administrator's Guide.

ESMRESP(data-area)

Returns the response code from RACF as a fullword binary variable. When RACF is in use, the possible values are the return codes that are supplied when you are using the RACF secured sign-on service to generate a PassTicket, as follows:

0: A PassTicket was produced.
8: A PassTicket was not produced.

ESMREASON(data-area)

Returns the reason code from RACF, as a fullword binary variable.

The possible values are the RACF reason codes that are supplied by the z/OS Security Server RACF Callable Services > GSS-API functions (Function code 2) > Subfunction codes > Wrap a message. 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.

Conditions

16 INVREQ

RESP2 values:

251: The interface between CICS and RACF is not active.
252: The value that is returned by RACF in ESMRESP is not classified by CICS. See the ESM documentation for an explanation of the ESMRESP and ESMREASON values.
254: RACF does not support requests for a PassTicket.

255: Invalid ENCRYPTKEY.
256: This command is not valid when you are running under the default user ID.
257: The ENCRYPTTOKEN option was specified, but the associated kerberos token originated from a system that does not support message confidentiality.

70 NOTAUTH

RESP2 values:

250: PassTicket not built successfully. RACF does not authorize a request for a PassTicket for the combination of the user ID associated with the task that issued this command, and the profile name that is specified in ESMAPPNAME.
260: RACF does not authorize a request to generate a PassTicket for this region.