REQUEST ENCRYPTPTKT
Request an external security manager to generate an encrypted PassTicket.
REQUEST ENCRYPTPTKT >>-REQUEST--ENCRYPTPTKT(ptr_ref)--FLENGTH(data-area)------------> >--ENCRYPTKEY(data-area)--ESMAPPNAME(data-value)----------------> >--+----------------------+--+--------------------+------------>< '-ESMREASON(data-area)-' '-ESMRESP(data-area)-'
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.
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.
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 security.racf.passticket.
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
signon 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 . SeeSubfunction 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.
