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 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 Security Server (RACF) 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 non-KDSR format:
//CSFTKDS JOB <JOB CARD PARAMETERS> //******************************************************************** //* Licensed Materials - Property of IBM * //* 5650-ZOS * //* Copyright IBM CORP. 2007, 2013 * //* * //* This JCL defines a VSAM TKDS * //* * //* 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 a TKDS. There are * //* samples for each of the other key data sets and formats. * //* * //******************************************************************** //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) - INDEX (NAME(CSF.CSFTKDS.INDEX)) /*SYS1.SAMPLIB CSFTKD2 member sample is used to define a TKDS in KDSR format://CSFTKD2 JOB <JOB CARD PARAMETERS> //******************************************************************** //* Licensed Materials - Property of IBM * //* 5650-ZOS * //* Copyright IBM CORP. 2013 * //* * //* This JCL defines a VSAM TKDS which is initialized to use common * //* record format * //* * //* 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 a TKDS which is * //* initialized to use common record format. There are * //* samples for each of the other key data sets and formats. * //* * //******************************************************************** //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) - 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) /*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.