(ZOS) Use the z/OS hardware cryptography leveraging ICSF and RACF keystores

Integrated Cryptographic Service Facility (ICSF) is the software on a z/OS system that serves as an interface with the hardware where keys can be stored. IBMJCECCARACFKS keystores handle certificates and keys managed in Resource Access Control Facility (RACF). The certificates are stored in RACF, but we can store keys in ICSF or RACF. The IBMJCECCARACFKS keystore will achieve hardware crypto exploitation, such as encryption, decryption and signing, regardless if the keys are in stored in RACF or in ICSF.

Before starting this task, we should become familiar with the content of the topic Hardware cryptographic device support for Web Services Security.

We must also:

• Ensure the necessary setup for placing you certificates in RACF have been completed. Refer to the z/OS Information Center for the version of z/OS running on the system, for information on how to place you certificates in RACF
• Know the CSFSERV access permissions required for the ICSF Services that the IBMJCECCA provider uses. Refer to the document Standard Edition, Hardware Cryptography IBMJCECCA Overview for information about these access permissions. This document is located at http://www.ibm.com/systems/z/os/zos/tools/java/products/j6jcecca.html

• Ensure that ICSF is running.

The JCECCARACFKS keystore type, is only available on the z/OS platform.

The JCECCAKS keystore is used for keys managed and store directly in ICSF and requires that you include the IBMJCECCA provider in the provider list specified in the java.security file.

The JCECCARACFKS keystore is used for certificates and keys managed in RACF. You store the certificates in RACF, and we can store the keys in either RACF or ICSF. Using the JCECCARACFKS keystore type requires that you include the IBMJCECCA provider in the provider list specified in the java.security file. We can achieve hardware crypto exploitation for performance benefit even when your keys are not stored in the hardware.

The JCERACFKS keystore is used with the IBMJCE provider or the IBMJCECCA provider. Use the JCERACFKS keystore for certificates and keys that are managed and stored by RACF. We can achieve hardware crypto exploitation for performance benefit, when using the IBMJCECCA provider. The URI path reference for the JCERACFKS keystore is in the form of safkeyring:///your_keyring_name.

If the key is going to be stored in the hardware, generating new keys in RACF requires using the ICSF option.

Tasks

1. Start the required ICSF services. Refer to JAVA and ICSF documentation for more information.
2. Locate the java.security file WAS_HOME/AppServer/properties. The java.security file is a symbolic link to a java security file in the SMP/E HFS. Delete the java.security file symbolic link and copy the file java.security from the SMP/E HFS to WAS_HOME/AppServer/properties so that it can be edited. In the java.security file uncomment the following IBMJCECCA provider in the provider list:

   security.provider.1=com.ibm.crypto.hdwrCCA.provider.IBMJCECCA
   

3. Renumber the remaining providers in the provider list.

4. Navigate to Security > SSL certificate and key management > Key stores and certificates.

5. Click New to create a new a new keystore.

6. Add the directory path to the keystore. The URI must contain safkeyringhw instead of safkeyring, for example, safkeyringhw:///your_keyring_name.

7. Select JCECCARACFKS for the Type and complete the rest of the fields as appropriate.

   If the token login is required, type the keystore password in the Password field.

   To be compatible with the JCE keystore in requiring a password, the JCERACFKS password is password. Security for this keystore is not really protected using a password as other keystore types, but rather it is based on the identity of the executing thread for protection with RACF. This password is for the keystore file specified in the Path field.

   Operations that use keys on the token require a secure login. This field is optional if the keystore is used as a cryptographic accelerator. In this case, we need to select the Enable cryptographic operations on hardware device option.

8. Click OK, then click Save to apply these changes to the master configuration.

   We might need to restart the servers before these changes take affect.

A keystore is now available to configure SSL connections.

What to do next

We can continue securing communication between the client and server using this keystore file when setting up an SSL configuration.

Related:

Hardware cryptographic device support for Web Services Security