TKDS Installations need to understand and plan for the system resources required for managing the TKDS copy in virtual storage, particularly when the installation is deploying a very large TKDS. Refer to ICSF System Resource Planning for the TKDS and Session Object Memory Areas for guidelines. Once you understand these guidelines, refer to Steps to create the TKDS for step-by-step instructions.

ICSF System Resource Planning for the TKDS and Session Object Memory Areas

Like the CKDS and PKDS, ICSF manages a mirror copy of the TKDS data set in protected, private virtual storage to optimize cryptographic workload access to persistent PKCS #11 objects (keys, certificates, and so on). Also like the CKDS and PKDS, the in-storage TKDS copy must be accommodated with sufficient system central storage and auxiliary paging space resources. Unfortunately, the variable length nature of PKCS #11 objects makes resource estimating for the TKDS difficult. The best way to estimate the virtual storage requirement for an existing, stable TKDS (one that is not experiencing significant dynamic PKCS #11 object creation or deletion activity) is to determine the actual size of the used DATA portion of the TKDS and multiply this by 3. The following formula is provided to help you calculate the required system virtual storage backing resource for an active in-storage TKDS. In this formula HI-A-RBA is the allocated relative byte address for the data component of a TKDS VSAM data set. The IDCAMS LISTCAT command output for a TKDS VSAM data set can be consulted to determine the HI-A-RBA value for the data component. The %Free Space used in this formula represents the percentage of free space in the TKDS VSAM data set. The IDCAMS EXAMINE DATATEST command output can be consulted to determine the percentage of free space.

HI-A-RBA x ( ( 100 - %Free Space ) / 100 ) x 3

For example, if the DATA HI-A-RBA has the value 1622016 with 56% free space, then the virtual storage requirement estimate would be 1622016 x (44/100) x 6 = 4282122 bytes or 4182 Kilobytes.

In addition to the persistent PKCS #11 objects stored in the TKDS, applications may also make use of temporary (session) objects. These too occupy ICSF protected, private virtual storage and should be accounted for. However, since these objects are not stored in the TKDS, it is impossible to estimate their virtual storage requirements without having some knowledge of the applications that are using PKCS #11. Fortunately, most applications that use PKCS #11 use only a small number of PKCS #11 session objects and their storage requirements are already factored into the TKDS estimate above. However, some applications, such as TCP/IP's IPSec, use session objects exclusively, and may use a large number of them. Estimating the virtual storage requirements for these is beyond the scope of this document. Note that applications using PKCS #11 session objects have an overall upper limit of 128 Megabytes per application address space for session objects.

Steps to create the TKDS

To enable applications to create and use persistent PKCS #11 tokens and objects using the PKCS #11 services, the TKDS must be allocated and the TKDS data set name must be specified on the TKDSN parameter of the options data set when you first start ICSF.

The TKDS must be a key-sequenced data set with variable length records. Allocate the TKDS on a permanently resident volume.

For detailed information about calculating space for a VSAM data set and an explanation of keyed-direct update processing and what happens when control area and control interval splits occur, see z/OS DFSMS Access Method Services for Catalogs.

1. Determine the amount of primary space you need to allocate for the TKDS.

   This should reflect the total number of entries you expect the data set to contain originally. The TKDS will contain PKCS #11 tokens and objects. Each record has a maximum size of 32 KB. A record for a token will use 0.1 KB. The minimum size of a record for objects is: Data: 1 KB, Secret Key: 1.1 KB, Public Key: 1.5 KB, Private Key: 3.4 KB, Certificate: 1 KB, Domain Parameter: 1.5KB. Allocate enough space for the number of tokens to be supported and for the number of objects to be created. Note that session objects are not stored in the TKDS.

2. Determine the amount of secondary space to allocate for the TKDS.

   This should reflect the total number of entries you expect to add to the data set.

   To access tokens and objects, VSAM uses the token handle or object handle as the VSAM key. This means that VSAM adds objects to the data set in collating sequence. That is, if two objects named A and B are in the data set, A appears earlier in the data set than B. As a result, adding objects to the data set can cause multiple VSAM control interval splits and control area splits. For example, a split might occur if the data set contains objects A, B, and E and you add C. In this case, C must be placed between B and E.

   The amount of secondary space you allocate must take into account the number of control interval and control area splits that might occur. If the TKDS uses a significant amount of secondary space, you can copy it into another disk copy that you created with more primary space. You can do this by using the Access Method Services (AMS) REPRO command or the AMS EXPORT/IMPORT commands.

   The BUFFERSPACE parameter on the AMS DEFINE CLUSTER command (required by Step 3) lets VSAM optimize space for control area and control interval splits.

3. Create an empty VSAM data set to use as the TKDS. Use the AMS DEFINE CLUSTER command to define the data set and to allocate its space. ICSF provides a sample job to define the TKDS in member CSFTKDS of SYS1.SAMPLIB.
   Note:

   To improve security and reliability of the data that is stored on the TKDS:

   • Use the ERASE and WRITECHECK parameters on the AMS DEFINE CLUSTER command. ERASE overwrites data records with binary zeros when the TKDS cluster is deleted. WRITECHECK provides hardware verification of all data that is written to the data set.
   • Create a Security Server (RACF) data set profile for the TKDS.
4. Allocate a disk copy of the TKDS by defining a VSAM cluster as in this SYS1.SAMPLIB CSFTKDS member sample:

   //CSFTKDS JOB = JOB CARD PARAMETERS
   //********************************************************************
   //*  Licensed Materials - Property of IBM                            *
   //*  5694-A01                                                        *
   //*  COPYRIGHT IBM CORP. 2007, 2009                                  *
   //*                                                                  *
   //* THIS JCL DEFINES A VSAM TKDS TO USE FOR ICSF                     *
   //*                                                                  *
   //*  CAUTION: This is neither a JCL procedure nor a complete JOB.    *
   //*  Before using this JOB step, you will have to make the following *
   //*  modifications:                                                  *
   //*                                                                  *
   //*  1) Add the job parameters to meet your system requirements.     *
   //*  2) Be sure to change CSF to the appropriate HLQ if you choose   *
   //*     not to use the default.                                      *
   //*  3) Change XXXXXX to the volid where you want your TKDS to       *
   //*     reside. The TKDS needs to be on a permanently resident       *
   //*     volume.                                                      *
   //*                                                                  *
   //* NOTE: This JCL is specific for creating the TKDS. There are      *
   //*       samples for each of the other key data sets.               *
   //*         CKDS  - CSFCKDS JCL                                      *
   //*         PKDS  - CSFPKDS JCL                                      *
   //*                                                                  *
   //********************************************************************
   //DEFINE EXEC PGM=IDCAMS,REGION=4M 
   //SYSPRINT DD SYSOUT=* 
   //SYSIN DD * 
     DEFINE CLUSTER (NAME(CSF.CSFTKDS) - 
                     VOLUMES(XXXXXX) - 
                     RECORDS(100,50) - 
                     RECORDSIZE(2200 32756) - 
                     KEYS(72 0) - 
                     FREESPACE(0,0) - 
                     SPANNED - 
                     SHAREOPTIONS(2,3)) - 
               DATA (NAME(CSF.CSFTKDS.DATA) - 
                     BUFFERSPACE(100000) - 
                     ERASE - 
                     WRITECHECK) - 
              INDEX (NAME(CSF.CSFTKDS.INDEX)) 
   /*

   You can change and use the Job Control Language according to the needs of your installation. For more information about allocating a VSAM data set, see z/OS DFSMS Access Method Services for Catalogs.