Example 3: Using the JCERACFKS or JCECCARACFKS Keystore on z/OS

If you use the JCERACFKS or JCECCARACFKS keystore you can take advantage of RACF® or both RACF and ICSF Security. They are supported only on the z/OS® platform. This is a keyring-based keystore. The certificate and public and private key pair are stored in RACF. The public and private key pair can optionally be stored in ICSF depending on the option specified when the key is created or imported.

Attention: You cannot use both JCERACFKS and JCECCARACFKS keystore types concurrently in the Security Key Lifecycle Manager for z/OS configuration file. You must specify only one of these types in the configuration file. If the JCERACFKS and JCECCARACFKS keystore types are used concurrently, the Security Key Lifecycle Manager for z/OS server will not start.

The JCERACFKS uses SAF and RACF services to protect key material and certificates. The JCECCARACFKS keystore uses SAF and RACF services with the addition of ICSF to protect certificates and key material. For SAF/RACF-stored key rings, the RACF RACDCERT command is the interface used to manage the keyring. The RACDCERT command is documented in the z/OS Security Server RACF Command Language Reference publication for more information, seehttp://publibz.boulder.ibm.com/epubs/pdf/ichza460.pdf.

For information about ICSF back up and recovery and Master Key management, see:

z/OS Cryptographic Services Integrated Cryptographic Service Facility System Programmer's Guide
z/OS Cryptographic Services Integrated Cryptographic Service Facility Administrator's Guide

The examples illustrate several ways to generate a public and private key pair and associated certificate where the public and private key pair is stored in the ICSF PKDS. The resulting certificate is then connected to a keyring which can be used by the Security Key Lifecycle Manager for z/OS to Write and Read encrypted tapes. This example also shows how to export the certificate and public key and import them so that they can be used by a business partner. The business partner can use it to write encrypted tapes that can be read by your Security Key Lifecycle Manager for z/OS.

Define a Keyring

You must define a keyring for the Security Key Lifecycle Manager for z/OS Server user ID on z/OS when using the JCERACFKS or JCECCARACFKS keystore types. Use the zOS RACF RACDCERT command as shown in the example. RACDCERT creates the keyring with the name of ISKLMRing for the user ID ISKLMSRV.

It is assumed that this command is being issued by an administrator who has authority to issue the RACDCERT command. See z/OS Security Server RACF Command Language Reference for additional information and a detailed explanation of the RACDCERT command and parameters. If you are using another z/OS security product, you must perform this task using the tooling that is appropriate for that security product.

RACDCERT ID(ISKLMSRV) ADDRING(ISKLMRing)

Ensure that the Security Key Lifecycle Manager for z/OS server is authorized to read from its keyring, and is authorized to use the key ICSF key label. Verify that the required RACF FACILITY class profiles are defined. If it is not defined issue the RDEFINE commands as shown to define these profiles which protect the use of keyring functions:

RDEFINE FACILITY IRR.DIGTCERT.LIST UACC(NONE)
RDEFINE FACILITY IRR.DIGTCERT.LISTRING UACC(NONE)
PERMIT IRR.DIGTCERT.LIST CLASS(FACILITY) ID(ISKLMSRV) ACC(READ)
PERMIT IRR.DIGTCERT.LISTRING CLASS(FACILITY) ID(ISKLMSRV) ACC(READ)

Generate a Certificate/RSA Key Pair

This example generates an RSA key pair and self-signed certificate. It then stores the RSA keys in the ICSF PKDS. The ICSF address space must be started for the key generation to be successful. The PCICC parameter of the RACDCERT GENCERT command indicates to RACF that the cryptographic hardware is to be used in the creation of the key pair. The SIZE indicates the modulus to be used in the creation of key pairs. The key label for the PKDS that is specified on the PCICC parameter must follow the z/OS data set naming conventions.

Note: The use of ICSF is optional. If you choose not to use ICSF, the key that you generate is saved in the RACF database and limited in strength to 1024 bits. This setting can be used in a testing environment.

You can use the self-signed certificate as is. You can then have it signed by a self-signed certificate authority certificate within RACF. You can optionally choose to export a certificate request and submit to a third-party certificate authority if your installation uses a third-party certificate authority. All three cases are illustrated in the examples in this section.

Use the RACDCERT GENCERT command to generate the RSA public and private key pair and create a self-signed certificate. In this example, the Security Key Lifecycle Manager for z/OS instance on z/OS will be executing with a z/OS user ID of ISKLMSRV. The subject distinguished name in the certificate that identifies this Security Key Lifecycle Manager for z/OS instance has a common name of ITOperations, for the company MyCo, in the United States. The certificate has a label associated with it of ISKLMServer to easily identity the certificate.

The RACDCERT GENCERT command has two possible keywords, PCICC (used in the following examples) and ICSF. Both stores the private key in the PKDS of ICSF with the following differences:

PCICC keyword: ICSF subsystem must be operational and configured for PKA operations.; A PCI-class cryptographic coprocessor must be operational.; The private key generated with RSA algorithm and stored as an ICSF RSA Chinese Remainder Theorem (CRT) key token in the PKDS.
ICSF keyword: ICSF subsystem must be operational and configured for PKA operations.; The private key is generated with RSA algorithm and stored as an ICSF RSA Modulus-Exponent (ME) key token in the PKDS.

For additional information see the RACF and ICSF documentation mentioned earlier in this document.

Generating a self-signed certificate
1. Generate an RSA key pair and certificate for the Security Key Lifecycle Manager for z/OS server instance on z/OS. The following RACDCERT command illustrates that the certificate generated uses ICSF for private key storage. The key size is 2048 bits and the private key is saved in the ICSF PKDS in an encrypted form.
```
RACDCERT GENCERT SUBJECTSDN(CN('ITOperations') 
O('MyCo') C('US')) WITHLABEL('ISKLMServer') 
PCICC(ITOPS.ISKLM.CERT) SIZE(2048)
```
  If you are not using ICSF omit the PCICC keyword and change the keysize to 1024.
  Note: This certificate can be used as is as a self-signed certificate or submitted to a third-party certificate provider for signing. See item 3 for information about submitting to a third-party certificate provider.
2. You can send this certificate to other business partners or sites within your enterprise. This is so that the certificate that identifies the Security Key Lifecycle Manager for z/OS instance on z/OS is known to your partners. By using this self-signed certificate, your business partners or remote sites agree to trust this certificate. This certificate can be imported into the keystore that is being used by the Security Key Lifecycle Manager for z/OS at your location of your partner. To send this certificate, you must export it to a dataset
```
RACDCERT EXPORT (LABEL('ISKLMServer')) 
DSN('hlq.PUBKEY.S2048.ITOPS') FORMAT(CERTDER)
```
  See Business Partner and Remote z/OS Systems for information.
3. You must ensure that the Security Key Lifecycle Manager for z/OS Server certificate is connected to the Security Key Lifecycle Manager for z/OS's keyring. This example shows connecting the certificate that identifies the Security Key Lifecycle Manager for z/OS server to the Security Key Lifecycle Manager for z/OS keyring. Modify these command examples to suit your needs.
```
RACDCERT ID(ISKLMSRV) CONNECT(LABEL('ISKLMServer')RING(ISKLMRing))
```
4. If you are using ICSF, ensure that the Security Key Lifecycle Manager for z/OS Server instance has RACF authority to the key label of the private key stored in the ICSF PKDS. Also be sure to refresh the in-storage copies of the CSFKEYS Class profiles:
```
RDEFINE CSFKEYS ITOPS.ISKLM.CERT  UACC(NONE)
PERMIT ITOPS.ISKLM.CERT CLASS(CSFKEYS) ID(ISKLMSRV) ACCESS(READ)
SETROPTS RACLIST(CSFKEYS) GENERIC(CSFKEYS) REFRESH
```
Generating a certificate signed by an Internal Certificate Authority
1. Generate a self-signed certificate authority certificate.
```
RACDCERT CERTAUTH GENCERT SUBJECTSDN(CN('MyLocalzOSCA')O('MyCo')C('US'))
WITHLABEL('LocalRACF CA') PCICC(LOCAL.RACF.CERTAUTH) SIZE(2048)
```
  If you are not using ICSF omit the PCICC keyword and change the keysize to 1024.
2. Generate an RSA key pair and certificate for the Security Key Lifecycle Manager for z/OS server instance on z/OS. The RACDCERT command illustrates that the certificate generated uses ICSF for private key storage. It is signed with the local certificate authority certificate generated in step 1.
```
RACDCERT ID(ISKLMSRV) GENCERT SUBJECTSDN(CN('ITOperations') 
O('MyCo') C('US')) WITHLABEL('ISKLMServer') PCICC(ITOPS.ISKLM.CERT) 
SIZE(2048) SIGNWITH(CERTAUTH LABEL('LocalRACF CA'))
```
  If you are not using ICSF omit the PCICC keyword and change the keysize to 1024.
3. You can send this certificate to other business partners or sites within your enterprise. This is so that the certificate that identifies the Security Key Lifecycle Manager for z/OS instance on z/OS is known to your partners. Validate with your business partners or remote sites that you trust a common certificate authority (CA) whether third party or self signed. This depends on your business and security practices. This certificate can be imported into the keystore that is being used by the Security Key Lifecycle Manager for z/OS at the location of your partner. To send this certificate, you must export it to a dataset.
```
RACDCERT EXPORT (LABEL('ISKLMServer')) DSN('hlq.PUBKEY.S2048.ITOPS') 
FORMAT(CERTDER)
```
  See Business Partner and Remote z/OS Systems for information.
4. Ensure that the Security Key Lifecycle Manager for z/OS Server certificate and its designated certificate authority certificate are connected to the key ring of the Security Key Lifecycle Manager for z/OS. These examples show connecting a certificate authority certificate. It also shows connecting the certificate that identifies the Security Key Lifecycle Manager for z/OS server to the Security Key Lifecycle Manager for z/OS keyring. Modify these command examples to suit your needs.
```
RACDCERT ID(ISKLMSRV) CONNECT(CERTAUTH LABEL('LocalRACF CA') RING(ISKLMRing))
RACDCERT ID(ISKLMSRV) CONNECT(LABEL('ISKLMServer')RING(ISKLMRing))
```
5. If you are using ICSF, ensure that the Security Key Lifecycle Manager for z/OS Server instance has RACF authority to the key label of the private key stored in the ICSF PKDS. Also be sure to refresh the in-storage copies of the CSFKEYS Class profiles:
```
RDEFINE CSFKEYS ITOPS.ISKLM.CERT  UACC(NONE)
PERMIT ITOPS.ISKLM.CERT CLASS(CSFKEYS) ID(ISKLMSRV) ACCESS(READ)
SETROPTS RACLIST(CSFKEYS) GENERIC(CSFKEYS) REFRESH
```
Generating a certificate signed by a third-party certificate authority
1. Generate an RSA key pair for the Security Key Lifecycle Manager for z/OS server instance on z/OS. The following RACDCERT command illustrates that the certificate generated uses ICSF for private key storage.
```
RACDCERT ID(ISKLMSRV) GENCERT SUBJECTSDN(CN('ITOperations') 
O('MyCo') C('US')) WITHLABEL('ISKLMServer') PCICC(ITOPS.ISKLM.CERT) SIZE(2048)
```
  If you are not using ICSF omit the PCICC keyword and change the keysize to 1024. The certificate can be submitted to a third-party certificate provider for signing.
2. Generate and save a certificate request to a dataset (hlq.PUBKEY.REQUEST.ITOPS)
```
RACDCERT GENREQ (LABEL(‘ISKLMServer')) DSN(‘hlq.PUBKEY.S2048.ITOPS') 
```
3. Submit certificate request, hlq.PUBKEY.S2048.ITOPS to your certificate provider. The response you receive is an X.509 certificate. This example assumes that the certificate you receive from your third-party certificate authority is saved in the dataset 'hlq.THIRD.PARTY.CERT' on z/OS. The contents of this dataset is imported into RACF. This dataset contains only the signed certificate that identifies the Security Key Lifecycle Manager for z/OS instance running on z/OS. It can also contain the certificate authority certificate. The private key for the Security Key Lifecycle Manager for z/OS certificate remains protected by either ICSF in the PKDS or RACF.
4. Receive the response into dataset 'hlq.THIRD.PARTY.CERT'.
5. Add the certificate to RACF.
```
RACDCERT ADD('hlq.THIRD.PARTY.CERT') TRUST 
WITHLABEL('ISKLMServer') ID(ISKLMSRV)
```
  If the CA certificate is not contained in the dataset ‘hlq.THIRD.PARTY.CERT' you need to acquire the CA certificate that signed the Security Key Lifecycle Manager for z/OS certificate from the External certificate authority. You must then add it to RACF as a CERTAUTH.
6. You can send this certificate to other business partners or sites within your enterprise. This is so that the certificate that identifies the Security Key Lifecycle Manager for z/OS instance on z/OS is known to your partners. Validate with your business partners or remote sites that you trust a common certificate authority (CA) whether third-party or self signed. This depends on your business and security practices. This certificate can be imported into the keystore that is being used by the Security Key Lifecycle Manager for z/OS at the location of your partner. To send this certificate, you must export it to a dataset
```
RACDCERT EXPORT (LABEL('ISKLMServer')) 
DSN('hlq.PUBKEY.S2048.ITOPS') FORMAT(CERTDER)
```
  See Business Partner and Remote z/OS Systems for information.
7. Ensure that the Security Key Lifecycle Manager for z/OS Server certificate and its designated certificate authority certificate are connected to the key ring of the Security Key Lifecycle Manager for z/OS. These examples show connecting a certificate authority certificate. It also shows connecting the certificate that identifies the Security Key Lifecycle Manager for z/OS server to the Security Key Lifecycle Manager for z/OS keyring. Modify these command examples to suit your needs.
```
RACDCERT ID(ISKLMSRV) CONNECT(CERTAUTH LABEL('External CA label') RING(ISKLMRing)) 

RACDCERT ID(ISKLMSRV) CONNECT(LABEL('ISKLMServer')RING(ISKLMRing))
```
  See Business Partner and Remote z/OS Systems for information.
8. If you are using ICSF, ensure that the Security Key Lifecycle Manager for z/OS Server instance has RACF authority to the key label of the private key stored in the ICSF PKDS. Also be sure to refresh the in-storage copies of the CSFKEYS Class profiles:
```
RDEFINE CSFKEYS ITOPS.ISKLM.CERT  UACC(NONE)
PERMIT ITOPS.ISKLM.CERT CLASS(CSFKEYS) ID(ISKLMSRV) ACCESS(READ)
SETROPTS RACLIST(CSFKEYS) GENERIC(CSFKEYS) REFRESH
```

Business Partner and Remote z/OS Systems

Another z/OS business partner, for example, or perhaps a remote z/OS site within your business would import the certificate into a z/OS dataset. They then use the RACDCERT to add that certificate to RACF. The public key in the certificate can also be saved in the ICSF PKDS depending on the operands supplied to the RACDCERT command.

Note: The KeyLabel you specify on the WITHLABEL option of the RACDCERT ADD command must match the KeyLabel that was used when the certificate was created. This only works if you plan to specify an encoding mechanism of Label "L" when encrypting tapes. Optionally, you can specify an encoding mechanism of Public Key Hash "H", which uses a Hash value rather than the KeyLabel to identify the key. While Hash gives slightly less performance, it allows you to import a certificate/public key without knowing the KeyLabel that was used to create/export the key. It also gives you the freedom to specify the KeyLabel you want to use to identify the public key of your business partner. Therefore using the Public Key Hash would be the preferred method. An example of how the z/OS encoding mechanism is specified in this section.

The following RADCERT ADD command imports the certificate and public key from the business partner contained in the 'dataset_containing_the_cert_received' with an alias CompanyXISKLMServer. In this example the imported alias of CompanyXISKLMServer does not match the original business partner's alias of ISKLMServer. This only works if you plan to specify an encoding mechanism of Public Key Hash "H" for this key as shown in the example. Otherwise the alias on the import command must be provided to you by your business partner.

RACDCERT ID(ISKLMSRV) ADD('dataset_containing_the_cert_received')  
TRUST WITHLABEL('CompanyXISKLMServer') PCICC(companyX.ISKLMSRV.cert)

If you are not using ICSF omit the PCICC keyword and change the keysize to 1024.

The WITHLABEL keyword associates a string or friendly name for the certificate being imported. This name is used by Security Key Lifecycle Manager for z/OS when accessing the certificate. See the z/OS Security Server RACF Command Language Reference for detailed discussion of the RACDCERT command.

On z/OS the encoding key mechanism can be specified in the data class or JCL. This is an example of how it would be specified in the JCL. It is best that you specify an encoding mechanism of Label "L" when defining your own Key. You must specify an encoding mechanism of Public Key Hash "H" when defining a business partner key.

//C02STRW1 JOB CONSOLE, 
// MSGCLASS=H,MSGLEVEL=(1,1),CLASS=B, 
// TIME=1440,REGION=2M 
/*JOBPARM SYSAFF=* 
//* 
//* ENC KEY MASTER JOB 
//* 
//CREATE1 EXEC PGM=IEBDG 
//SYSPRINT DD SYSOUT=* 
//SEQ001 DD DSN=TAPE.C02M5CX2.PC5.NOPOOL.C02STRS1.MASTER, 
// KEYLABL1='ISKLMServer', 
// KEYENCD1=L, 
// KEYLABL2='CompanyXISKLMServer', 
// KEYENCD2=H, 
// LABEL=(1,SL),UNIT=C02M5CX2,DISP=(,CATLG), 
// DCB=(DSORG=PS,RECFM=FB,LRECL=2048,BLKSIZE=6144) 
//SYSIN DD * 
DSD OUTPUT=(SEQ001) 
FD NAME=A,STARTLOC=1,LENGTH=10,FORMAT=ZD,INDEX=1 
FD NAME=B,STARTLOC=11,LENGTH=13,PICTURE=13,'PRIMER RECORD' 
CREATE QUANTITY=25,FILL='Z',NAME=(A,B) 
END 
/*

For more information about the Hash encoding mechanism, see z/OS DFSMS Software Support for IBM® System Storage® TS1130 and TS1120 Tape Drive (3592), SC26-7514.

You must ensure that this certificate is connected (or associated) with the keyring of the Security Key Lifecycle Manager for z/OS server. Use the RACDCERT command as shown in the example. This example assumes that the Security Key Lifecycle Manager for z/OS keyring on this z/OS system is ISKLMRing. It also assumes that the z/OS user ID associated with the Security Key Lifecycle Manager for z/OS process is ISKLMSRV.

Note: As this certificate contains only a public key, it is important that the USAGE(CERTAUTH) option is used. If it is not specified, the Security Key Lifecycle Manager for z/OS does not start. This is because it believes that the certificate that was added must also contain a private key.

RACDCERT ID(ISKLMSRV) CONNECT(LABEL('CompanyXISKLMServer') 
RING(ISKLMRing) USAGE(CERTAUTH))

RACDCERT ID(ISKLMSRV) CONNECT(CERTAUTH LABEL('GENERATED CA Label FROM ADD') 
RING(ISKLMRing))

On this remote z/OS system, ensure that the Security Key Lifecycle Manager for z/OS server is authorized to read from its keyring. It must also be authorized to use the key ICSF key label. Ensure that the required RACF FACILITY class profiles are defined. If not, issue the RDEFINE commands to define these profiles which protect the use of keyring functions:

RDEFINE FACILITY IRR.DIGTCERT.LIST UACC(NONE)
RDEFINE FACILITY IRR.DIGTCERT.LISTRING UACC(NONE)
 
PERMIT IRR.DIGTCERT.LIST CLASS(FACILITY) ID(ISKLMSRV) ACC(READ)
PERMIT IRR.DIGTCERT.LISTRING CLASS(FACILITY) ID(ISKLMSRV) ACC(READ)

If using ICSF, ensure that the Security Key Lifecycle Manager for z/OS Server instance has RACF authority to the key label of the private key stored in the ICSF PKDS. Also, issue refresh for the in-storage copies of the CSFKEYS Class profiles:

RDEFINE CSFKEYS REMOTE.ISKLM.CERT  UACC(NONE)
PERMIT REMOTE.ISKLM.CERT CLASS(CSFKEYS) ID(ISKLMSRV) ACCESS(READ)
SETROPTS RACLIST(CSFKEYS) GENERIC(CSFKEYS) REFRESH

For information about how to use this certificate containing the public key when encrypting data to tape, see z/OS DFSMS Software Support for IBM System Storage TS1130 and TS1120 Tape Drives (3592), SC26-7514.

Verifying the Keyring can be accessed by the Java Keytool/Hwkeytool

Before starting the Security Key Lifecycle Manager for z/OS you must validate that the keystore is accessible in the Java hwkeytool (for JCECCARACFKS/ICSF keys) or Java keytool (for JCERACFKS/non-ICSF keys).

The examples show how you would use both hwkeytool and keytool to list the contents of the keyring.

For ICSF keys:

hwkeytool -debug -J-Djava.protocol.handler.pkgs=com.ibm.crypto.hdwrCCA.provider 
-list -keystore safkeyring://ISKLMSRV/ISKLMRing -storetype JCECCARACFKS

For keys not in ICSF:

keytool -debug -J-Djava.protocol.handler.pkgs=com.ibm.crypto.provider 
-list -keystore safkeyring://ISKLMSRV/ISKLMRing -storetype JCERACFKS