How To
Summary
The JVM on z/OS can make use of the following cryptographic providers for encryption, decryption and SSL operations.
IBMZSecurity (software provider)
IBMJCECCA (hardware provider)
IBMJCEHYBRID (hybrid provider)
Java must be at service level 11.0.15.0 or higher take advantage of these providers.
Objective
This document provides the steps necessary to enable the IBMZSecurity, IBMJCECCA and IBMJCEHYBRID providers to make use of hardware cryptography, and to provide failover from hardware to software providers when running with Java 11 in a Liberty for z/OS server.
Environment
Liberty for z/OS with IBM Semeru Runtime Certified Edition for z/OS Version 11 (Java 11)
Steps
To enable the IBMZSecurity provider
Steps 1 and 2 can be skipped if the JVM is at service level 11.0.17.0 or later.
The IBMZSecurity provider is enabled by default due to its position in the JAVA_HOME/conf/security/java.security file.
In releases before 11.0.17.0, the IBMZSecurity provider is not enabled by default
1. Create a file called java.security in the same directory as your server.xml, and add the IBMZSecurity provider as in the example below:
------------
security.provider.1=IBMZSecurity
security.provider.2=OpenJCEPlus
security.provider.3=SUN
security.provider.4=SunRsaSign
security.provider.5=SunEC
security.provider.6=SunJSSE
security.provider.7=SunJCE
security.provider.8=SunJGSS
security.provider.9=SunSASL
security.provider.10=XMLDSig
security.provider.11=SunPCSC
security.provider.11=JdkLDAP
security.provider.12=JdkSASL
security.provider.13=SunPKCS11
security.provider.1=IBMZSecurity
security.provider.2=OpenJCEPlus
security.provider.3=SUN
security.provider.4=SunRsaSign
security.provider.5=SunEC
security.provider.6=SunJSSE
security.provider.7=SunJCE
security.provider.8=SunJGSS
security.provider.9=SunSASL
security.provider.10=XMLDSig
security.provider.11=SunPCSC
security.provider.11=JdkLDAP
security.provider.12=JdkSASL
security.provider.13=SunPKCS11
------------
The providers above come from JAVA_HOME/conf/security/java.security file and are included in the list after IBMZSecurity provider.
The providers are renumbered starting with IBMZSecurity.
2. In the same directory as your server.xml, create a file called jvm.options containing the location of the new java.security file.
-Djava.security.properties=${server.config.dir}/java.security
Although it is possible to edit the JAVA_HOME/conf/security/java.security file, the JVM is usually installed in a file system that is read only, and the file will get overwritten when new Java maintenance is installed. By using the custom property java.security.properties, the server can append new providers to the existing java.security file shipped by the JVM,
and changes will remain when Java maintenance is applied.
Note that a single "=" sign used by java.security.properties indicates the changes in this file will append to the JVM's java.security file. This ensures that the providers in the newly created java.security file will take effect over the settings in the JAVA_HOME/conf/security/java.security file.
Avoid using a double "==" sign after java.security.properties as this will override all settings in the JAVA_HOME/conf/security/java.security file with the new java.security file that was created.
3. Ensure that the server.xml has the either the transportSecurity-1.0 or ssl-1.0 feature enabled.
------------
<feature>transportSecurity-1.0</feature>
or
<feature>ssl-1.0</feature>
<feature>ssl-1.0</feature>
------------
4. Ensure the correct location and type are specified in the keystore tag in the server.xml.
------------
<keyStore id="CellDefaultKeyStore"
location="safkeyringjce:///LibertyKeyring"
location="safkeyringjce:///LibertyKeyring"
filebased="false"
password="password" type="JCERACFKS"/>
password="password" type="JCERACFKS"/>
<keyStore id="CellDefaultTrustStore"
location="safkeyringjce:///LibertyKeyring"
location="safkeyringjce:///LibertyKeyring"
filebased="false"
password="password" type="JCERACFKS"/>
password="password" type="JCERACFKS"/>
-----------
To enable the IBMJCECCA provider.
1 . Follow all steps To enable the IBMZSecurity provider first, and confirm that SSL is working with the IBMZSecurity provider.
2. Create a file called java.security in the same directory as your server.xml, and update the java.security file to contain the
IBMJCECCA as the first provider,
IBMZSecurity as the second provider
as in the example below:
------------
security.provider.1=IBMJCECCA
security.provider.2=IBMZSecurity
security.provider.3=OpenJCEPlus
security.provider.4=SUN
security.provider.5=SunRsaSign
security.provider.6=SunEC
security.provider.7=SunJSSE
security.provider.8=SunJCE
security.provider.9=SunJGSS
security.provider.10=SunSASL
security.provider.11=XMLDSig
security.provider.12=SunPCSC
security.provider.13=JdkLDAP
security.provider.14=JdkSASL
security.provider.15=SunPKCS11
security.provider.2=IBMZSecurity
security.provider.3=OpenJCEPlus
security.provider.4=SUN
security.provider.5=SunRsaSign
security.provider.6=SunEC
security.provider.7=SunJSSE
security.provider.8=SunJCE
security.provider.9=SunJGSS
security.provider.10=SunSASL
security.provider.11=XMLDSig
security.provider.12=SunPCSC
security.provider.13=JdkLDAP
security.provider.14=JdkSASL
security.provider.15=SunPKCS11
------------
The providers above come from JAVA_HOME/conf/security/java.security file and are included in the list after IBMJCECCA and IBMZSecurity providers.
3. In the same directory as your server.xml, create a file called jvm.options containing the location of the new java.security file.
-Djava.security.properties=${server.config.dir}/java.security
4. Ensure the correct location and type are specified in the keystore tag in the server.xml.
If the certificate has its private key in software, but the JVM is leveraging the crypto device to offload crypto operations.
------------
<keyStore id="CellDefaultKeyStore"
location="safkeyringjce:///LibertyKeyring"
location="safkeyringjce:///LibertyKeyring"
filebased="false"
password="password" type="JCERACFKS"/>
password="password" type="JCERACFKS"/>
<keyStore id="CellDefaultTrustStore"
location="safkeyringjce:///LibertyKeyring"
location="safkeyringjce:///LibertyKeyring"
filebased="false"
password="password" type="JCERACFKS"/>
password="password" type="JCERACFKS"/>
------------
If the certificate has its private key in hardware or both hardware and software, and the JVM is leveraging the crypto device to offload crypto operations as well as access the certificate's private key from the crypto device.
------------
<keyStore id="CellDefaultKeyStore"
location="safkeyringjcecca:///LibertyKeyring"
location="safkeyringjcecca:///LibertyKeyring"
filebased="false"
password="password" type="JCECCARACFKS"/>
password="password" type="JCECCARACFKS"/>
<keyStore id="CellDefaultTrustStore"
location="safkeyringjcecca:///LibertyKeyring"
location="safkeyringjcecca:///LibertyKeyring"
filebased="false"
password="password" type="JCECCARACFKS"/>
password="password" type="JCECCARACFKS"/>
------------
When using only the IBMJCECCA provider with a personal certificate that has its private key in hardware, the location must be safkeyringjcecca and the type must be JCECCARACFKS.
The following RACF command can be used to identify certificates with keys in hardware crypto.
RACDCERT LIST(label('personal_certificate_labelname')) ID(Liberty_ID)
For example the certificate might show a private key of type ICSF or a private key with a PKDS label.
------------
Private Key: ICSF
or
Private Key: YES
PKDS Label: IRR.DIGTCERT.Liberty_ID.xxx.nnnnnnnnnn
PKDS Label: IRR.DIGTCERT.Liberty_ID.xxx.nnnnnnnnnn
------------
5. If you protect ICSF services using rules in the CSFSERV class, the Liberty server's userid must be permitted to the necessary ICSF callable services.
The following RACF command can be used to determine if CSFSERV is active under "ACTIVE CLASSES"
SETROPTS LIST
The following RACF command can be used to determine which ICSF callable services in the CSFSERV class are defined.
RLIST CSFSERV * ALL
Permit the Liberty for z/OS ID to the ICSF callable services in the CSFSERV resource class which can be found in
RACF CSFSERV resource requirements from z/OS Cryptographic Services information center.
Below is an example command to permit the
Liberty_ID to ICSF callable service CSFDSV in the CSFSERV resource class.
------------
RDEFINE CSFSERV CSFDSV UACC(NONE)
PERMIT CSFDSV CLASS(CSFSERV) ID(Liberty_ID) ACCESS(READ)
SETROPTS RACLIST(CSFSERV) REFRESH
PERMIT CSFDSV CLASS(CSFSERV) ID(Liberty_ID) ACCESS(READ)
SETROPTS RACLIST(CSFSERV) REFRESH
------------
To enable the IBMJCEHYBRID provider.
1 . Follow all steps To enable the IBMJCECCA provider first, and confirm that SSL is working with the IBMJCECCA provider.
The IBMJCEHYBRID provider does not do any cryptographic operations, but routes requests to JCE providers registered with the Java Security Framework. It will make use of the IBMJCECCA provider, and provides failover to the IBMZSecurity provider in the event that the IBMJCECCA provider experiences a problem. For example, if the Liberty server is started with the ICSF address space stopped.
It is recommended that you attempt the setup for the IBMJCECCA provider first before switching to the IBMJCEHYBRID provider. It becomes difficult to confirm whether the IBMJCECCA provider is working as expected since the IBMJCEHYBRID provider may be in its failover process to the IBMZSecurity provider when an SSL operation is taking place.
2. Create a file called java.security in the same directory as your server.xml, and update the java.security file to contain
IBMJCEHYBRID as the first provider,
IBMJCECCA as the second provider,
IBMZSecurity as the third provider
as in the example below:
------------
security.provider.1=IBMJCEHYBRID
security.provider.2=IBMJCECCA
security.provider.3=IBMZSecurity
security.provider.4=OpenJCEPlus
security.provider.5=SUN
security.provider.6=SunRsaSign
security.provider.7=SunEC
security.provider.8=SunJSSE
security.provider.9=SunJCE
security.provider.10=SunJGSS
security.provider.11=SunSASL
security.provider.12=XMLDSig
security.provider.13=SunPCSC
security.provider.14=JdkLDAP
security.provider.15=JdkSASL
security.provider.16=SunPKCS11
security.provider.2=IBMJCECCA
security.provider.3=IBMZSecurity
security.provider.4=OpenJCEPlus
security.provider.5=SUN
security.provider.6=SunRsaSign
security.provider.7=SunEC
security.provider.8=SunJSSE
security.provider.9=SunJCE
security.provider.10=SunJGSS
security.provider.11=SunSASL
security.provider.12=XMLDSig
security.provider.13=SunPCSC
security.provider.14=JdkLDAP
security.provider.15=JdkSASL
security.provider.16=SunPKCS11
------------
The providers above come from JAVA_HOME/conf/security/java.security file and are included in the list after IBMJCEHYBRID, IBMJCECCA and IBMZSecurity providers.
3. Change location and type specified in the keystore tag in the server.xml.
------------
<keyStore id="CellDefaultKeyStore"
location="safkeyringjcehybrid:///LibertyKeyring"
filebased="false"
password="password" type="JCEHYBRIDRACFKS"/>
<keyStore id="CellDefaultTrustStore"
location="safkeyringjcehybrid:///LibertyKeyring"
filebased="false"
password="password" type="JCEHYBRIDRACFKS"/>
------------
When using the IBMJCEHYBRID provider,
the location must be safkeyringjcehybrid and the type must be JCEHYBRIDRACFKS.
Additional Information
Reference Links:
Document Location
Worldwide
[{"Type":"MASTER","Line of Business":{"code":"LOB45","label":"Automation"},"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SSD28V","label":"WebSphere Application Server Liberty Core"},"ARM Category":[{"code":"a8m3p000000F7yQAAS","label":"IBM WebSphere Liberty-All Platforms-\u003ELiberty Security-\u003ELiberty - SSL"}],"ARM Case Number":"","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"All Versions"}]
Was this topic helpful?
Document Information
Modified date:
25 January 2023
UID
ibm16840291