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. It is recommended that the TKDS is cataloged in the master catalog.
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 Commands.
- 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. In addition, installations may add metadata to any record. If you are planning to add metadata, account for the size of the metadata in the length of records. Note that session objects are not stored in the TKDS.
- 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.
- 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 parameter on the AMS DEFINE CLUSTER command. ERASE overwrites data records with binary zeros when the TKDS cluster is deleted.
- Create a data set profile for the TKDS. Ensure that no one has access to the TKDS data set by protecting the TKDS data set name resource in the DATASET class. If a data set profile is used, as opposed to using the PROTECTALL(FAIL) option for example, the profile should have a UACC of NONE.
- Allocate a disk copy of the TKDS by defining a VSAM cluster with one of the
following samples:SYS1.SAMPLIB CSFTKDS member sample is used to define a TKDS in KDSR format as the target of a reencipher or coordinated conversion:
//CSFTKDS JOB <JOB CARD PARAMETERS> //******************************************************************** //* Licensed Materials - Property of IBM * //* 5650-ZOS * //* Copyright IBM CORP. 2007, 2021 * //* * //* This JCL defines a VSAM TKDS in the common record format (KDSR) * //* * //* NOTE: If creating a VSAM TKDS as the target of reencipher, * //* coordinated change master key, or coordinated convert * //* operations, you should use this sample, not CSFTKD2. * //* * //* 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. Do not specify * (asterisk) for the volid. * //* * //* NOTE: This JCL is specific for creating a TKDS which is * //* in common record format and is to be used as the target * //* for reencipher or a coordinated operation. * //* * //******************************************************************** //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) - SHAREOPTIONS(2,3)) - DATA (NAME(CSF.CSFTKDS.DATA) - BUFFERSPACE(100000) - CONTROLINTERVALSIZE(32768) - ERASE) - INDEX (NAME(CSF.CSFTKDS.INDEX)) /*SYS1.SAMPLIB CSFTKD2 member sample is used to define a TKDS in KDSR format (for first time initialization only)://CSFTKD2 JOB <JOB CARD PARAMETERS> //******************************************************************** //* Licensed Materials - Property of IBM * //* 5650-ZOS * //* Copyright IBM CORP. 2013, 2021 * //* * //* This JCL defines a VSAM TKDS which is initialized to use common * //* record format for first time TKDS initialization only. * //* * //* NOTE: If creating a VSAM TKDS as the target of reencipher, * //* coordinated change master key, or coordinated convert * //* operations, you should use sample CSFTKDS, not this one. * //* * //* 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. Do not specify * (asterisk) for the volid. * //* * //* NOTE: This JCL is specific for creating a TKDS which is * //* initialized for first time use in common record format. * //* Use sample CSFTKDS as the target for reencipher or a * //* coordinated operation. * //* * //******************************************************************** //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) - SHAREOPTIONS(2,3)) - DATA (NAME(CSF.CSFTKDS.DATA) - BUFFERSPACE(100000) - CONTROLINTERVALSIZE(32768) - ERASE) - INDEX (NAME(CSF.CSFTKDS.INDEX)) /* //*-------------------------------------------------------------------* //* Repro header record into the TKDS * //*-------------------------------------------------------------------* //MKHEAD EXEC PGM=IEBGENER //SYSPRINT DD SYSOUT=* //SYSUT1 DD * //SYSUT2 DD DSN=&&GENTMP,UNIT=SYSDA,DISP=(,PASS), // DCB=(RECFM=FB,LRECL=156,BLKSIZE=1560),SPACE=(TRK,(1,1)) //SYSIN DD * GENERATE MAXFLDS=10,MAXLITS=156 RECORD FIELD=(20,X'0000000000000000000000000000000000000000',,1), FIELD=(20,X'0000000000000000000000000000000000000000',,21), FIELD=(20,X'E3C8C4D900000000000000000000000000000000',,41), FIELD=(20,X'0000000000000000000000000000000000000000',,61), FIELD=(16,X'00000000000000000000000000000000',,81), FIELD=(16,X'00000000000000000000000000000000',,97), FIELD=(4,X'0000009C',,113), FIELD=(16,X'00000000000000000000000000000000',,117), FIELD=(20,X'0000000000000000000000000000000000000000',,133), FIELD=(4,X'00000200',,153) /* //REPROKSD EXEC PGM=IDCAMS //SYSPRINT DD SYSOUT=* //SYSDATA DD DSN=*.MKHEAD.SYSUT2,DISP=(OLD,DELETE) //SYSIN DD * REPRO INFILE(SYSDATA) - OUTDATASET(CSF.CSFTKDS) /*When running in a GDPS environment, there are certain attributes that are required to allow TKDS updates to be propagated to another sysplex. If that's the case, allocate a disk copy of the TKDS by defining a VSAM cluster as in this SYS1.SAMPLIB CSFTKD3 member sample://CSFTKD3 JOB <JOB CARD PARAMETERS> //******************************************************************** //* Licensed Materials - Property of IBM * //* 5650-ZOS * //* Copyright IBM CORP. 2020, 2021 * //* * //* This JCL defines a VSAM TKDS initialized to use common record * //* format which also supports replication in a GDPS environment. * //* * //* NOTE: If creating a VSAM TKDS as the target of reencipher, * //* coordinated change master key, or coordinated convert * //* operations, you should only use the DEFINE step. * //* * //* 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. Do not specify * (asterisk) for the volid. * //* 4) Change lsname to match the logstream name on the logstream * //* definition. * //* * //* NOTE: This JCL is specific for creating a TKDS initialized to * //* use common record format which also supports replication * //* in a GDPS environment. You should not use this template if * //* the TKDS is not being replicated as that would cause * //* unnecessary overhead. There are samples available for all * //* key data sets and formats in GDPS and non-GDPS * //* environments. * //* * //******************************************************************** //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) - SHAREOPTIONS(2,3) - LOGREPLICATE - LOGSTREAMID(lsname) - FRLOG(NONE)) - DATA (NAME(CSF.CSFTKDS.DATA) - BUFFERSPACE(100000) - CONTROLINTERVALSIZE(32768) - ERASE) - INDEX (NAME(CSF.CSFTKDS.INDEX)) /* //*-------------------------------------------------------------------* //* Repro header record into the TKDS * //*-------------------------------------------------------------------* //MKHEAD EXEC PGM=IEBGENER //SYSPRINT DD SYSOUT=* //SYSUT1 DD * //SYSUT2 DD DSN=&&GENTMP,UNIT=SYSDA,DISP=(,PASS), // DCB=(RECFM=FB,LRECL=156,BLKSIZE=1560),SPACE=(TRK,(1,1)) //SYSIN DD * GENERATE MAXFLDS=10,MAXLITS=156 RECORD FIELD=(20,X'0000000000000000000000000000000000000000',,1), FIELD=(20,X'0000000000000000000000000000000000000000',,21), FIELD=(20,X'E3C8C4D900000000000000000000000000000000',,41), FIELD=(20,X'0000000000000000000000000000000000000000',,61), FIELD=(16,X'00000000000000000000000000000000',,81), FIELD=(16,X'00000000000000000000000000000000',,97), FIELD=(4,X'0000009C',,113), FIELD=(16,X'00000000000000000000000000000000',,117), FIELD=(20,X'0000000000000000000000000000000000000000',,133), FIELD=(4,X'00000200',,153) /* //REPROKSD EXEC PGM=IDCAMS //SYSPRINT DD SYSOUT=* //SYSDATA DD DSN=*.MKHEAD.SYSUT2,DISP=(OLD,DELETE) //SYSIN DD * REPRO INFILE(SYSDATA) - OUTDATASET(CSF.CSFTKDS) /*If instead, an existing TKDS is being altered to support replication in a GDPS environment, the following attributes need to be added: LOGREPLICATE, LOGSTREAMID, and FRLOG. The following shows a sample job step which can be tailored to alter the attributes of an existing TKDS to support a GDPS environment://ALTER EXEC PGM=IDCAMS //SYSPRINT DD SYSOUT=* //SYSIN DD * ALTER - CSF.CSFTKDS - LOGREPLICATE - LOGSTREAMID(lsname) - FRLOG(NONE) /*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 Commands.