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

ICSF System Resource Planning for the PKDS

Like the CKDS and TKDS, ICSF manages a mirror copy of the PKDS data set in protected, private virtual storage to optimize cryptographic workload access to asymmetric keys. Again, similar to the CKDS, the in-storage PKDS copy must be accommodated with sufficient system central storage and auxiliary paging space resources. The same formula used in the system resource planning section for the CKDS can be used to estimate the virtual storage requirement for an existing, stable PKDS (one that is not experiencing significant dynamic asymmetric key creation or deletion activity).

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

As described in ICSF System Resource Planning for the CKDS, the output from running the IDCAMS LISTCAT and EXAMINE DATATEST commands against a PKDS VSAM data set can be consulted to determine the data set's data component HI-A-RBA and the percentage of free space in the data set.

Steps to create the PKDS

The PKDS must be allocated and the PKDS data set name must be specified on the PKDSN parameter of the options data set when you first start ICSF. ICSF support for the PCICC, PCIXCC, CEX2C, or CEX3C requires a PKDS. Even if not available at first time start up, a PCICC, PCIXCC, CEX2C, or CEX3C can be dynamically configured online. Since ICSF can not tell if a PCICC, PCIXCC, CEX2C, or CEX3C will be added, it requires the PKDS to be available at start up.

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

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

   This should reflect the total number of entries you expect the data set to contain originally. The PKDS will contain both public and private PKA keys. Each record has a maximum size of 2.8 KB. The average record length for a private key is 1 KB, and for a public key is 0.5 KB. Allocate space for a minimum of two private keys, one for digital signatures, and another for encipherment. In addition, allocate enough space for the number of public keys you expect to store in the PKDS. The number of public keys varies from system to system. Generally, only those keys that are received from other users or systems are stored in the PKDS. The public keys are used to send messages to the owners of the public keys.

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

   This should reflect the total number of entries you expect to add to the data set. For detailed information about calculating space for a VSAM data set, see z/OS DFSMS Access Method Services for Catalogs.

   To access keys, VSAM uses the key label as the VSAM key. This means that VSAM adds keys to the data set in collating sequence. That is, if two keys named A and B are in the data set, A appears earlier in the data set than B. As a result, adding keys 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 keys 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 PKDS 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. For a detailed 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.

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

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

   • Use the ERASE and WRITECHECK parameters on the AMS DEFINE CLUSTER command. ERASE overwrites data records with binary zeros when the PKDS 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 PKDS.
   • The CISZ(8192) coded in this sample in the DATA section is a hardcoded requirement.
4. Allocate a disk copy of the PKDS by defining a VSAM cluster as in this SYS1.SAMPLIB CSFPKDS member sample:

   //CSFPKDS JOB = JOB CARD PARAMETERS
   //********************************************************************
   //*  Licensed Materials - Property of IBM                            *
   //*  5694-A01                                                        *
   //*  Copyright IBM Corp. 2002, 2009                                  *
   //*                                                                  *
   //* THIS JCL DEFINES A VSAM PKDS 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 PKDS to       *
   //*     reside. The PKDS needs to be on a permanently resident       *
   //*     volume.                                                      *
   //*                                                                  *
   //* NOTE: This JCL is specific for creating the PKDS. There are      *
   //*       samples for each of the other key data sets.               *
   //*         CKDS  - CSFCKDS JCL                                      *
   //*         TKDS  - CSFTKDS JCL                                      *
   //*                                                                  *
   //********************************************************************
   //DEFINE EXEC PGM=IDCAMS,REGION=4M 
   //SYSPRINT DD SYSOUT=* 
   //SYSIN DD * 
     DEFINE CLUSTER (NAME(CSF.CSFPKDS) - 
                     VOLUMES(XXXXXX) - 
                     RECORDS(100,50) - 
                     RECORDSIZE(350,3800) - 
                     KEYS(72 0) - 
                     FREESPACE(0,0) - 
                     SHAREOPTIONS(2,3)) - 
               DATA (NAME(CSF.CSFPKDS.DATA) - 
                     BUFFERSPACE(100000) - 
                     ERASE - 
                     CISZ(8192) - 
                     WRITECHECK) - 
              INDEX (NAME(CSF.CSFPKDS.INDEX)) 
   /*

   You can change and use the Job Control Language according to the needs of your installation. Please note that the JCL to define the PKDS differs from the JCL that defines the CKDS (RECORDSIZE and CISZ parameters). For more information about allocating a VSAM data set, see z/OS DFSMS Access Method Services for Catalogs.

Migrating to a larger PKDS

In ICSF HCR7750, the LRECL for the PKDS increased. This change allows 4096-bit RSA public and private keys to be stored in the PKDS. With ICSF release HCR7750 or later, ICSF expects the PKDS to have the longer LRECL before it will start.

If you currently have a PKDS that ICSF is using and are planning to move to

• the ICSF HCR7750 or later web deliverable
• z/OS V1.10 or later

then you need to perform the following steps before starting the new version of ICSF.

The steps take you through the tasks that must be performed to make an exact copy of the old PKDS contents. The ICSF PKA services are not available during the time the copy is made to ensure the PKDS contents are not changing. You need to schedule the change for a period of time when the applications using the PKDS keys are also not available.

The steps to migrate are:

1. If the PKDS is shared with down-level systems, install the toleration APAR on those systems to allow continued sharing of the PKDS. The toleration APAR number is OA21807.
   Note:

   Even with toleration APAR OA21807 installed, however, be aware that reencipherment of a larger PKDS must always be performed on an HCR7750 or later system.
2. Create the larger PKDS - use the JCL in SYS1.SAMPLIB(CSFPKDS) from the HCR7750 or later system. If the PKDS will be shared, place the VSAM data set where it can be shared.
3. Suspend activity with the PKDS:
   • On HCR7751 and lower releases, disable the PKDS READ, PKDS WRITE, PKDS CREATE, and PKDS DELETE access from the ADMINCNTL option. This will prevent any updates from being made while the migration action is performed. It will affect applications that use the PKDS services.
   • On HCR7770, disable the Dynamic PKDS access from the ADMINCNTL option. This will prevent any updates from being made while the migration action is performed. It will affect applications that use the PKDS services.
4. If the old PKDS is not empty, copy it to the larger PKDS using the JCL in SYS1.SAMPLIB(CSFPKDCP) from the HCR7750 system. If the original PKDS is an empty one, you will need to initialize the new PKDS.

   //CSFPKDCP <JOB CARD PARAMETERS> 
   //********************************************************************
   //* Licensed Materials - Property of IBM                             *
   //* 5694-A01                                                         *
   //* Copyright IBM Corp. 2007                                         *
   //*                                                                  *
   //* THIS JCL COPIES ONE VSAM PKDS TO THE LARGER PKDS                 *
   //*                                                                  *
   //* 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.                                          *
   //*                                                                  *
   //********************************************************************
   //STEP1 EXEC PGM=IDCAMS,REGION=4M
   //SYSPRINT DD SYSOUT=*
   //INDD DD DSN=CSF.CSFPKDS.OLD,DISP=SHR
   //OUTDD DD DSN=CSF.CSFPKDS,DISP=SHR
   //SYSIN DD *
   REPRO INFILE(INDD) OUTFILE(OUTDD)
   /*

5. Protect the VSAM data set from use by non-authorized personnel.
6. Update the ICSF started procedures on all systems to reference the new PKDS.
7. Activate the new PKDS on each system - Refresh the PKDS from the Master Key Mgmt option on the main ICSF Administration panel.
8. Resume activity with the PKDS:
   • On HCR7751 and lower releases, enable the PKDS READ, PKDS WRITE, PKDS CREATE, and PKDS DELETE access from the ADMINCNTL option. Resume any applications that use the PKDS services.
   • On HCR7770, enable the Dynamic PKDS access from the ADMINCNTL option. Resume any applications that use the PKDS services.

Another approach is to stop ICSF, create the new PKDS, perform the copy, update the installation options data set, and restart ICSF.