Setting up the started task ID and creating a key ring for it

Use the instructions in this section to create a functional RACF ID and associate that ID with the SQL Tuning Services started task. After the ID is created, add the ID to an existing key ring or create a new key ring.

Step 1: Create the SQL Tuning Services started task ID

About this task

The following instructions cover the basic requirements for the SQL Tuning Services. However, your site might have additional requirements. Work with your security administrator to create an ID that is appropriate for your environment.

Procedure

Issue the following RACF commands to create the started task ID for the SQL Tuning Services started task. In the following example, the name of the started task ID is SQLTSID:

/* Create the started task USERID for the SQL Tuning */
/* Services started task    */

ADDUSER SQLTSID  +
NOPASSWORD. +
ALTUSER SQLTSID OMVS(AUTOID SHARED) +
ALTUSER SQLTSID OMVS(HOME('/usr/home') PROGRAM('/bin/sh')) +
SETROPTS GENERIC(DATASET) REFRESH

Store the SQL Tuning Services started task as a member of **.PROCLIB. A sample job, DSN5STRT, is provided for the SQL Tuning Services started task in the hlq.SDSN5TSA data set.

Issue the following RACF commands to associate the started task ID with the started task job:

RALTER STARTED  DSN5STRT.** UACC(NONE) -
STDATA(USER(SQLTSID) GROUP(SYS1) PRIVILEGED(NO) -
TRUSTED(NO) TRACE(NO))
SETROPTS RACLIST(STARTED) REFRESH

If your site uses any of the z/OS® authorized services described in the following topic, create SERVER profiles for the ones that you use:
https://www.ibm.com/docs/en/was-liberty/zos?topic=liberty-enabling-zos-authorized-services-zos
Note: You might receive warning messages about these services when you start the SQL Tuning Services server. If you don’t use these services in your environment, you can ignore the warning messages.

Step 2: Create a key ring for network communications

SQL Tuning Services supports the use of a key ring-based keystore (JCERACFKS) or a file-based keystore (PKCS12). This task provides instructions only for creating a new key ring-based keystore and associating that key ring with the SQL Tuning Services server started task. A key ring is a set of digital certificates, private keys, and key mappings that defines a networking trust policy. A key ring keystore collects and manages all the key rings. If you are using a file-based keystore, consult with your security administrator.

About this task

SQL Tuning Services supports the following HTTPS security options for connecting a client to the SQL Tuning Services server:

Through Liberty TLS
Through AT-TLS

The example in this section uses Liberty TLS. If your environment uses AT-TLS, see Configuring AT-TLS for SQL Tuning Services for more information.

Notes: You might already have a TLS key ring that can enable the SQL Tuning Services server to communicate with Db2® for z/OS. You can reuse this key ring for SQL Tuning Services, or you can create a new key ring. If you use an existing key ring, the started task ID (SQLTSID) must have UPDATE authority to the <ringOwner><ringName>.LST resource in the RDATALIB class. See the following z/OS topic for more information:https://www.ibm.com/docs/en/zos/3.1.0?topic=library-usage-notes.

Procedure

To create a new key ring:

Define certificates and key ring permissions.

Copy and save the following example JCL to your system, then customize and submit the JCL. In our example, we use the following value:

!CERTMGR! - SQLTSID

After you customize the job, save and submit it.

//******************************************************************** 
//* DEFINE CERTIFICATES AND KEY RING PERMISSIONS BY USING RACF. 
//* 
//* BEFORE RUNNING THE JOB, REPLACE THE FOLLOWING PLACEHOLDERS: 
//*   !CERTMGR! 
//*     THE ADMINISTRATIVE USER ID THAT IS USED FOR CREATING 
//*     AND MANAGING KEY RINGS AND CERTIFICATES IN RACF. 
//******************************************************************** 
//STEP1    EXEC PGM=IKJEFT01,DYNAMNBR=20,TIME=1440,REGION=32M 
//SYSTSPRT DD SYSOUT=* 
//SYSTSIN  DD * 
 /******************************************************************** 
 /* ACTIVATE REQUIRED SAF CLASSES AND DEFINE REQUIRED RESOURCES 
 /******************************************************************** 
 SETROPTS CLASSACT(DIGTCERT DIGTRING) 
 RDEFINE FACILITY IRR.DIGTCERT.ADD       UACC(NONE) 
 RDEFINE FACILITY IRR.DIGTCERT.ADDRING   UACC(NONE) 
 RDEFINE FACILITY IRR.DIGTCERT.CONNECT   UACC(NONE) 
 RDEFINE FACILITY IRR.DIGTCERT.EXPORT    UACC(NONE) 
 RDEFINE FACILITY IRR.DIGTCERT.GENCERT   UACC(NONE) 
 RDEFINE FACILITY IRR.DIGTCERT.LIST      UACC(NONE) 
 RDEFINE FACILITY IRR.DIGTCERT.LISTRING  UACC(NONE) 
 RDEFINE FACILITY IRR.DIGTCERT.MAP       UACC(NONE) 
 /******************************************************************** 
 /* GIVE CERT MANAGER USER ID SUFFICIENT ACCESS TO MANAGE 
 /* CERTIFICATES AND KEY RINGS ON BEHALF OF STARTED TASK USER IDS 
 /* AND FOR CERTIFICATE AUTHORITIES 
 /******************************************************************** 
 PERMIT IRR.DIGTCERT.ADD CLASS(FACILITY) ID(!CERTMGR!) - 
        ACC(CONTROL) 
 PERMIT IRR.DIGTCERT.ADDRING CLASS(FACILITY) ID(!CERTMGR!) - 
        ACC(UPDATE) 
 PERMIT IRR.DIGTCERT.CONNECT CLASS(FACILITY) ID(!CERTMGR!) - 
        ACC(CONTROL) 
 PERMIT IRR.DIGTCERT.EXPORT CLASS(FACILITY) ID(!CERTMGR!) - 
        ACC(CONTROL) 
 PERMIT IRR.DIGTCERT.GENCERT CLASS(FACILITY) ID(!CERTMGR!) - 
        ACC(CONTROL) 
 PERMIT IRR.DIGTCERT.LIST CLASS(FACILITY) ID(!CERTMGR!) - 
        ACC(CONTROL) 
 PERMIT IRR.DIGTCERT.LISTRING CLASS(FACILITY) ID(!CERTMGR!) - 
        ACC(UPDATE) 
 PERMIT IRR.DIGTCERT.MAP CLASS(FACILITY) ID(!CERTMGR!) - 
        ACC(UPDATE) 
 /******************************************************************** 
 /* ACTIVATE ALL OF THE ABOVE CHANGES 
 /******************************************************************** 
 SETR RACLIST (DIGTRING) REFRESH 
 SETR RACLIST (DIGTCERT) REFRESH 
 SETR RACLIST (FACILITY) REFRESH 
/*

Generate key pairs, certificates, and the key ring.

Copy and save the following example JCL to your system, then customize and submit the JCL. This example uses the following values:

!USERID! - SQLTSID 
!RINGNAME! - SQLTSKR

After you customize the job, save and submit it.

//RACFCERT JOB MSGCLASS=G,MSGLEVEL=(1,1),CLASS=G,REGION=32M, 
//         USER=RACF000,PASSWORD=C0DESHOP 
//********************************************************************  
//* GENERATE KEY PAIRS, CERTIFICATES, AND KEY RINGS USING RACF.  
//* Z/OS RACF SERVES AS THE LOCAL CERTIFICATE AUTHORITY (CA).  
//*  
//* BEFORE RUNNING THE JOB, REPLACE THE FOLLOWING PLACEHOLDERS: 
//*   !USERID!  
//*     THE USER ID THAT IS THE OWNER OF THE USER CERTIFICATE.  
//*     THIS SHOULD BE THE USER ID THAT IS ASSOCIATED WITH THE  
//*     STARTED TASK.  
//*   !SYSNAME! 
//*     THE Z/OS SYSTEM NAME. THIS IS USED TO LABEL THE USER  
//*     CERTIFICATE.  
//*   !RINGNAME!  
//*     THE NAME OF THE KEY RING TO CREATE. 
//********************************************************************  
//STEP1 EXEC PGM=IKJEFT01,DYNAMNBR=20,TIME=1440,REGION=32M  
//SYSTSPRT DD SYSOUT=*  
//SYSTSIN DD * 
/********************************************************************  
/* GENERATE A KEY PAIR AND CERTIFICATE FOR THE CERTIFICATE AUTHORITY 
/********************************************************************  
RACDCERT CERTAUTH -  
         GENCERT -  
         SUBJECTSDN(OU('DB2') -  
                    O('IBM') -  
                    L('SVL') -  
                    SP('CA') -  
                    C('US')) -  
         NOTAFTER(DATE(2099-12-31)) -  
         WITHLABEL('LOCALCA') -  
         KEYUSAGE(CERTSIGN) 
/********************************************************************  
/* GENERATE A KEY PAIR AND CERTIFICATE FOR A USER/ENTITY 
/********************************************************************  
RACDCERT ID(!USERID!) -  
         GENCERT -  
         SUBJECTSDN(CN('!SYSNAME!') -  
                    OU('SVL') -  
                    C('US')) -  
         NOTAFTER(DATE(2099-12-31)) -  
         WITHLABEL('!SYSNAME! CA CERT') -  
         SIGNWITH(CERTAUTH LABEL('LOCALCA')) 
/********************************************************************  
/* CREATE A KEY RING AND CONNECT THE CERTIFICATES AND KEYS 
/********************************************************************  
RACDCERT ID(!USERID!) ADDRING(!RINGNAME!)  
RACDCERT ID(!USERID!) CONNECT(CERTAUTH -  
                              LABEL('LOCALCA') -  
                              RING(!RINGNAME!) -  
                              USAGE(CERTAUTH))  
RACDCERT ID(!USERID!) CONNECT(ID(!USERID!) -  
                              LABEL('!SYSNAME! CA CERT') -  
                              RING(!RINGNAME!) -  
                              USAGE(PERSONAL) -  
                              DEFAULT)  
/*