REQUEST ENCRYPTPTKT

Request an external security manager to generate an encrypted PassTicket.

REQUEST ENCRYPTPTKT

Conditions: NOTAUTH, INVREQ

This command is threadsafe.

Description

The REQUEST ENCRYPTPTKT command requests an external security manager (ESM), such as RACF®, to generate an encrypted PassTicket.

A PassTicket that is not encrypted is a password substitute that your program can use to sign on to a particular application on a particular system, such as another CICS® region. You must use the ESMAPPNAME option to specify the profile name by which the external security manager refers to the application to which you are signing on.

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 the external security manager 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.

Note: A request for a PassTicket succeeds if a userid is revoked, but an attempt to sign on with that userid and PassTicket fails.

A PassTicket must be used within 10 minutes of being generated. If the PassTicket times out (because, for example, of a session failure), your application must generate another PassTicket before you can attempt to sign on again. Repeated failed sign-on attempts with PassTickets can result in the user ID being revoked.

Before you use PassTickets, you must ensure that the system clocks for the target system and the originating system are synchronized to within the valid time range. You must also define a Secure Signon key for each target system. For information on the requirements for using PassTickets, see Generating and using 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. If the external security manager is RACF, for more information about RACF profile names and PassTickets, see Using the secured signon function in z/OS Security Server RACF Security Administrator's Guide.

ESMRESP(data-area)

Returns the response code from the external security manager, 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 the external security manager, as a fullword binary variable.

If the external security manager is RACF, 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 the external security manager is not active.
252: The value that is returned by the external security manager in ESMRESP is not classified by CICS.
254: The external security manager 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. The external security manager 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: The external security manager does not authorize a request to generate a PassTicket for this region.