TKE host transaction program setup

The TKE Host Transaction Program (TKE HTP) is the host-based part of Trusted Key Entry. It forms the interface between the TKE workstation and the host crypto modules.

The TKE HTP (server) needs to be started before a TKE workstation (client) can communicate with the host crypto modules. The TKE HTP consists of a started procedure (CSFTTCP) which passes some start-up parameters to a REXX clist (CSFTHTP3). The clist then calls a module (CSFTTKE) that does RACF® authorization checking to make sure that no unauthorized clients get to the TKE HTP server.

In order to run the new TKE Host Transaction program, the CSFTTKE module must be added to the authorized command list in IKJTSOxx on the system where the TKE HTP server will be started.

Perform these steps to install the server:

Update the authorized commands list in the TSO/E commands and programs member, IKJTSOxx, in the SYS1.PARMLIB data set.

Figure 1. Format of AUTHCMD

AUTHCMD NAMES(                    /* AUTHORIZED COMMANDS */            +
       COMMAND1                   /*                     */            +
       COMMAND2                   /*                     */            +
       COMMAND3                   /*                     */            +
           .                                                           + 
           .                                                           +
           .                                                           +
       CSFTTKE                    /* AUTHORIZE TKE       */            +
           .                                                           +
           .                                                           + 
           .                                                           +

Set up system security
You will associate a RACF profile or group with the TKE Host Transaction Program. The userid or group associated with the TKE host transaction program must be authorized to all the APIs in the CSFSERV class it will use.
```
PERMIT CSFCRC  CLASS(CSFSERV) ID(userid or group) ACCESS(READ)
PERMIT CSFKIM  CLASS(CSFSERV) ID(userid or group) ACCESS(READ)
PERMIT CSFKRC  CLASS(CSFSERV) ID(userid or group) ACCESS(READ)
PERMIT CSFKRD  CLASS(CSFSERV) ID(userid or group) ACCESS(READ)
PERMIT CSFKRR  CLASS(CSFSERV) ID(userid or group) ACCESS(READ)
PERMIT CSFKRW  CLASS(CSFSERV) ID(userid or group) ACCESS(READ)
PERMIT CSFKYT  CLASS(CSFSERV) ID(userid or group) ACCESS(READ)
PERMIT CSFKYT2 CLASS(CSFSERV) ID(userid or group) ACCESS(READ)
PERMIT CSFPCI  CLASS(CSFSERV) ID(userid or group) ACCESS(READ)
PERMIT CSFPKRC CLASS(CSFSERV) ID(userid or group) ACCESS(READ)
PERMIT CSFPKRW CLASS(CSFSERV) ID(userid or group) ACCESS(READ)
PERMIT CSFPKI CLASS(CSFSERV) ID(userid or group) ACCESS(READ)
SETROPTS RACLIST(CSFSERV) REFRESH
```
To protect module CSFTTKE from unauthorized users, you must protect it using RACF. For more information, refer to z/OS Security Server RACF Security Administrator's Guide and z/OS Security Server RACF System Programmer's Guide.

See z/OS Security Server RACF Command Language Reference for the correct command syntax. You might need to work with your security administrator, because these RACF commands are not available to the general user.

This example permits the user ID or group assigned to the CSFTTCP started task to the CSFTTKE profile in the FACILITY class:
Figure 2. Assign a user ID to CSFTTKE in FACILITY class
```
SETR CLASSACT(FACILITY)
SETR RACLIST(FACILITY)
RDEFINE FACILITY CSFTTKE UACC(NONE) 
PERMIT CSFTTKE CLASS(FACILITY) ID(userid or group) ACCESS(READ)
SETROPTS RACLIST(FACILITY) REFRESH 
```
The module (CSFTTKE) must also be protected, using the APPL class to control which users can use the application when they enter the system.
This example assigns a user ID or group to the CSFTTKE profile in the APPL class:
Figure 3. Assign a User ID to CSFTTKE in APPL Class
```
SETR CLASSACT(APPL)
SETR RACLIST(APPL)
RDEFINE APPL CSFTTKE UACC(NONE)
PERMIT CSFTTKE CLASS(APPL) ID(userid or group) ACCESS(READ) 
SETROPTS RACLIST(APPL) REFRESH 
```
Note: The user IDs or groups of user IDs must be permitted to use the TKE workstation.
If you do not have a generic user ID associated to all started procedures, you can associate a user ID to the CSFTTCP proc by issuing a RACF RDEFINE command. For more information, see z/OS Security Server RACF Security Administrator's Guide.

Note: The RACF user ID associated with the CSFTTCP proc must have a valid OMVS segment.
This example assigns a user ID or group to the started task CSFTTCP:
Figure 4. Assign a user ID to a started task
```
SETR CLASSACT(STARTED)
SETR RACLIST(STARTED)
RDEFINE STARTED CSFTTCP.CSFTTCP STDATA(USER(userid))
SETROPTS RACLIST(STARTED) REFRESH  
```
The TKE Host Transaction program must be started before you can logon to the host from TKE. A sample startup procedure is shipped in SYS1.SAMPLIB(CSFTTCP) and included here. Copy this procedure to your proclib data set and customize it for your installation.
Figure 5. Sample startup procedure
```
//CSFTTCP  PROC LEVEL=CSF,MEMBER=CSFTHTP3, 
//            CPARM='PORT;50003;SET DISPLAY LEVEL;TRACE ALL' 
//CLIST    EXEC PGM= IKJEFT01, 
//            PARM='EX ''&LEVEL..SCSFCLI0(&MEMBER)'' ''&CPARM'' EXEC' 
//STEPLIB   DD DSN=EZA.SEZALINK,DISP=SHR
//SYSABEND  DD SYSOUT=*
//SYSPRINT  DD SYSOUT=*  
//SYSEXEC   DD DSN=&LEVEL..SCSFCLI0,DISP=SHR   
//SYSPROC   DD DSN=&LEVEL..SCSFCLI0,DISP=SHR     
//SYSTSPRT  DD SYSOUT=*    
//SYSTSIN   DD DUMMY 
//TKEPARMS  DD DSN=&LEVEL..SAMPLIB(CSFTPRM),DISP=SHR  
//*
//* customize the DSN to be the TCP/IP data set on your system  
//*
//*SYSTCPD   DD DSN=TCPIP.SEZAINST(TCPDATA),DISP=SHR
//         PEND CSFTTCP    
//* -----------------------------------------------------------------
```
TKE startup parameters

Startup parameters may be passed to the TKE Host Transaction Program in a JCL parm field (CPARM) or in a data set referenced in the TKEPARMS DD statement. Parameters specified on the CPARM field override the parameters in the TKEPARMS data set. A sample TKEPARMS data set is shipped in SYS1.SAMPLIB(CSFTPRM).
These parameters are allowed:
- SET THE TKE DATA SETS;CM data set name
  The CM data set will contain the crypto module descriptions, domain descriptions, and authority information for a host. If the data set name does not exist, TKE will automatically create it on the host the first time you send updates to it. If you do not specify a CM data set name, TKE uses a default data set name of 'smfid.TKECM'.
  Note: A fully qualified data set name may not be specified on the CPARM field. Use the TKEPARMS to set the fully qualified TKECM data set name.
  Here are some examples:
  - Example 1: SET THE TKE DATA SETS;TKECM
    TKE will use data set name 'generic_id.TKECM'. The generic_id is the user ID assigned to the STARTED class for this proc.
  - Example 2: SET THE TKE DATA SETS;'TKEV3.TKECM'
    TKE will use data set name 'TKEV3.TKECM'.
- SET DISPLAY LEVEL;trace level
  This parameter sets the amount of trace information that is written to the job log of the started proc. The valid options are:
  - TRANSACTION TRACE - Logs HTP input and output transaction data
  - TRACE ALL - logs all HTP activities, including all TCP/IP verb return codes and information, input and output transaction data, and ICSF input and output data
  - TRACE NON-ZERO - Logs TCP/IP verbs with non-zero return codes only (this is the default if display level is not specified)
- PORT;port number
  This parameter defines the TCP/IP application port number that the started proc will use. This port number should be reserved in your TCP/IP profile for CSFTTCP to prevent other applications from using this port. This port number must be specified at the TKE workstation when defining a host (see TKE TCP/IP setup).
  
  If a port number is not specified, a default port of 50003 will be used. However, if port 50003 is not reserved in your TCP/IP profile, another application may use it and the TKE HTP will fail.
  
  For example: PORT;1000
SYSTCPD is optional but, depending on your TCP/IP installation, may be needed.
You may choose between implicit and explicit allocation.
- Implicit - The name of the configuration data set is constructed at run time, based on rules implemented in the components of TCP/IP. Once a data set name is constructed, TCP/IP uses the dynamic allocation services of z/OS to allocate the configuration data set.
- Explicit - TCP/IP searches for a specific DD name allocation for some configuration data sets. If you allocated a DD name with a DD statement in the JCL used to start a TCP/IP component, TCP/IP will read its configuration data from that allocation. It will not construct a configuration data set name for dynamic allocation.
Start the TKE server from the z/OS system console:
Figure 6. Start the TKE server
```
S CSFTTCP
```

Note: If you encounter problems during the start of CSFTTCP, the documented Errortype and Reason Codes are located within the REXX clist CSFTHTP3.