Configuring z/OSMF providers and ciphers

Environment

z/OSMF and Migrating from earlier releases of IBM SDK, Java Technology Edition

If you are migrating from IBM SDK, Java Technology Edition Version 8, the name is changed from IBM SDK, Java Technology Edition to IBM Semeru Runtime Certified Edition.

Semeru releases contain class libraries from the OpenJDK project rather than proprietary class libraries that are licensed from Oracle. 

Of note, many of the security providers in the IBM security implementation (such as the ones below) are replaced with the OpenJDK security implementation:

https://www.ibm.com/docs/en/semeru-runtime-ce-z/11.0.0?topic=migrating-from-earlier-releases-sdk-java-technology-edition

Java Cryptography

The Java Cryptography Architecture (JCA) is a framework for accessing and developing cryptographic functionality for the Java platform.

It includes APIs for a large variety of cryptographic services, including the following:

• Message digest algorithms
• Digital signature algorithms
• Symmetric bulk and stream encryption
• Asymmetric encryption
• Password-based encryption (PBE)
• Elliptic Curve Cryptography (ECC)
• Key agreement algorithms
• Key generators
• Message Authentication Codes (MACs)
• Secure Random Number Generators
   

https://docs.oracle.com/en/java/javase/11/security/java-security-overview1.html#GUID-C6D250FC-F147-4284-A6BF-8384DFD39DA6

The Java Cryptography Extension (JCE) provides a framework and implementations for encryption, key generation and key agreement, and Message Authentication Code (MAC) algorithms. Support for encryption includes symmetric, asymmetric, block, and stream ciphers. The software also supports secure streams and sealed objects. JCE has a provider-based architecture. Providers signed by a trusted entity can be plugged into the JCE framework, and new algorithms can be added seamlessly.

The JCE release includes two software components:

• the framework that defines and supports cryptographic services that providers can supply implementations for. This framework includes everything in the javax.crypto package.

• a provider named "IBMJCE"

z/OSMF and Providers

A Java Security Provider is a pluggable cryptographic service implementation that extends the Java Cryptography Architecture (JCA) by providing concrete implementations of cryptographic algorithms, key management, and security services. 

Providers contain a package (or a set of packages) that supply concrete implementations for the advertised cryptographic algorithms. Each JDK installation has one or more providers installed and configured by default. Additional providers may be added statically or dynamically. Clients may configure their runtime environment to specify the provider preference order. The preference order is the order in which providers are searched for requested services when no specific provider is requested. 

IBMJCEHYBRID Provider

Java™ Cryptography Extension Hybrid Provider (IBMJCEHYBRID) routes application requests for cryptography to different JCE providers, depending on their availability. Applications that use cryptographic hardware can use IBMJCEHYBRID to provide failover to another JCE provider to continue cryptographic operations when the hardware is not available.

https://www.ibm.com/docs/en/semeru-runtime-ce-z/11.0.0?topic=guide-ibmjcehybrid

IBMJSSE2 Provider

The Java™ Secure Socket Extension (JSSE) is a Java package that enables secure internet communications. The package implements a Java version of SSL (Secure Sockets Layer) and TLS (Transport Layer Security) protocols. It includes functions for data encryption, server authentication, message integrity, and optional client authentication.

https://www.ibm.com/docs/en/sdk-java-technology/8?topic=guide-ibmjsse2-provider

In Semeru releases, the Oracle JSSE provider is used instead of the IBM® JSSE2 provider. Differences between these providers might require code changes to your applications. For JSSE provider differences, review Table 1 at https://www.ibm.com/docs/en/semeru-runtime-ce-z/11.0.0?topic=security-jsse-provider-differences

Aspects of IBM JSSE2 and their equivalents in Oracle JSSE

Refer to table 1: https://www.ibm.com/docs/en/semeru-runtime-ce-z/11.0.0?topic=security-jsse-provider-differences for the name changes between Java 8 and 11.

IBMJCECCA Provider

The IBMJCECCA provider extends Java™ Cryptography Extension (JCE) and Java Cryptography Architecture (JCA) seamlessly to add support for hardware cryptography.

IBMJCECCA relies on ICSF to be operational and functional.

https://www.ibm.com/docs/en/sdk-java-technology/8?topic=components-ibmjcecca

https://www.ibm.com/docs/en/semeru-runtime-ce-z/11.0.0?topic=guide-ibmjcecca

IBMZSecurity Provider

The IBMZSecurity provider provides keystore functions for JCERACFKS keystore. 

A keystore is a Java™ object that contains a collection of keys and certificates that are referenced by unique labels or alias names. For most Java keystores, the persistent data is stored in a file. However, the persistent data for a JCERACFKS keystore is stored in the system Resource Access Control Facility (RACF®) database and connected to a RACF key ring. This type of keystore is available only on z/OS® systems that have RACF installed. Due to the nature of the RACF and key rings, the behavior of JCERACFKS keystore during update operations differs from the behavior of file-based keystore.

IBMZSecurity provider is required to use the safkeyringjce syntax. More on safkeyringjce later.

https://www.ibm.com/docs/en/semeru-runtime-ce-z/11.0.0?topic=guide-ibmzsecurity

Differences between IBM and Oracle versions of JCE

https://www.ibm.com/docs/en/sdk-java-technology/8?topic=reference-appendix-g-differences-between-oracle-versions-jce

IBMJCEPlus Provider

The IBMJCEPlus and IBMJCEPlusFIPS cryptographic providers are implementations of the Java™ Cryptography Extensions (JCE) APIs, which include, for example: ciphers, signatures, message digests, MACs and HMACs, secure random number generation, and key generation.

https://www.ibm.com/docs/en/sdk-java-technology/8?topic=guide-ibmjceplus-ibmjceplusfips-providers

Note, if CPACF is not installed on the IBM Z processor, z/OSMF may fail to start up with exception:

"Caused by java.security.ProviderException: Failed to initialize OpenJCEPlus provider".

This OpenJCEPlus requirement for CPACF is in the following SDK for Java and Semeru Versions and maintenance levels, and onwards: 

• Semeru 21, all maintenance levels
• Semeru 17.0.13.0
• Semeru 11.0.25.0
• Java 8.0.8.35

This requirement is because the SDK for Java and Semeru versions ship an ICC library in which a performance improvement is done with TRNG which requires CPACF.

https://www.ibm.com/support/pages/apar/PH67301

IBM SDK, Java 8 default security providers

This release has been tested with the following default security providers (/usr/lpp/java/J8.0_64/lib/security): 

• security.provider.1=com.ibm.jsse2.IBMJSSEProvider2

• security.provider.2=com.ibm.crypto.plus.provider.IBMJCEPlus

• security.provider.3=com.ibm.crypto.provider.IBMJCE

• security.provider.4=com.ibm.security.jgss.IBMJGSSProvider

• security.provider.5=com.ibm.security.cert.IBMCertPath

• security.provider.6=com.ibm.security.sasl.IBMSASL

• security.provider.7=com.ibm.xml.crypto.IBMXMLCryptoProvider

• security.provider.8=com.ibm.xml.enc.IBMXMLEncProvider

• security.provider.9=com.ibm.security.jgss.mech.spnego.IBMSPNEGO

• security.provider.10=sun.security.provider.Sun

https://www.ibm.com/docs/en/sdk-java-technology/8?topic=guide-general-information-about-security-providers

z/OSMF 2.5 (PH48850) security providers list overrides 

(/usr/lpp/zosmf/defaults/servers/zosmfServer/jvm.security.override.properties) Java 8 default security provider list from above:

• security.provider.1=com.ibm.crypto.ibmjcehybrid.provider.IBMJCEHYBRID
• security.provider.2=com.ibm.crypto.hdwrCCA.provider.IBMJCECCA
• security.provider.3=com.ibm.jsse2.IBMJSSEProvider2
• security.provider.4=com.ibm.crypto.provider.IBMJCE
• security.provider.5=com.ibm.security.jgss.IBMJGSSProvider
• security.provider.6=com.ibm.security.cert.IBMCertPath
• security.provider.7=com.ibm.security.sasl.IBMSASL
• security.provider.8=com.ibm.xml.crypto.IBMXMLCryptoProvider
• security.provider.9=com.ibm.xml.enc.IBMXMLEncProvider
• security.provider.10=com.ibm.security.jgss.mech.spnego.IBMSPNEGO
• security.provider.11=sun.security.provider.Sun
• security.provider.12=com.ibm.crypto.plus.provider.IBMJCEPlus

IBM Semeru 11 default security providers

This release has the following default security providers list and preference order (/usr/lpp/java/J11.0_64/conf/security/java.security):

• security.provider.1=OpenJCEPlus
• security.provider.2=IBMZSecurity
• 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.12=JdkLDAP
• security.provider.13=JdkSASL
• security.provider.14=SunPKCS11

https://docs.oracle.com/en/java/javase/11/security/oracle-providers.html#GUID-F41EE1C9-DD6A-4BAB-8979-EB7654094029 

z/OSMF 3.1 and 3.2 security providers list overrides 

(/usr/lpp/zosmf/defaults/servers/zosmfServer/jvm.security.override.properties) the Semeru default security provider list from above:

• 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 precedence

The JCA offers a set of APIs that allow users to query which providers are installed and what services they support.
In any given Java Virtual Machine (JVM), providers are installed in a given preference order, the order in which the provider list is searched if a specific provider is not requested. For example, suppose there are two providers installed in a JVM, PROVIDER_1 and PROVIDER_2. Assume that:

• PROVIDER_1 implements SHA-256 and DESede.
  PROVIDER_1 has preference order 1 (the highest priority).
• PROVIDER_2 implements SHA256withDSA, SHA-256, RC5, and RSA. 
  PROVIDER_2 has preference order 2.

Now let's look at three scenarios: 

1. If we are looking for a SHA-256 implementation, then both providers supply such an implementation. The PROVIDER_1 implementation is returned since PROVIDER_1 has the highest priority and is searched first.
2. If we are looking for an SHA256withDSA signature algorithm, PROVIDER_1 is first searched for it. No implementation is found, so PROVIDER_2 is searched. Since an implementation is found, it is returned.
3. Suppose we are looking for a SHA256withRSA signature algorithm. Since no installed provider implements it, a NoSuchAlgorithmException is thrown.

https://docs.oracle.com/javase/8/docs/technotes/guides/security/crypto/CryptoSpec.html

Setting the provider list in z/OSMF

You can force the use of a particular security providers list for z/OSMF. To override z/OSMF providers list, create /global/zosmf/configuration/local_override.cfg file. In it, add:

JVM_OPTIONS=’-Djava.security.properties=/global/zosmf/configuration/jvm.security.ov'

Note: z/OSMF requires local_override.cfg should contain a blank line at the end of the file.

Create/update /global/zosmf/configuration/jvm.security.ov with the list of providers you wish to use. You must maintain sequential numbering of each provider entry in the ordered list.

To verify the server has picked up your custom security property override file successfully, you can generate a Javacore with the following MODIFY command:

F <zosmf_server_name >,javacore

For z/OSMF, the Javacore file will be genereated in the /global/zosmf /data/logs/zosmfServer/

folder. Towards the top of the Javacore, look for the UserArgs section where you’ll find all the user options the JVM is using which should include the -Djava.security.properties statement that should be set to /global/zosmf/configuration/jvm.security.ov.

z/OSMF and TLS

The z/OSMF server port uses Java SSL encryption to protect its outbound HTTPS connections. In z/OSMF 2.5, the default protocol used in SSL_TLSv2.

 The IBMJSSE2 provider supports the following protocol parameters in application code. 

The following table shows which protocols are enabled by default for client and server connections. Note that security and system properties such as jdk.tls.disabledAlgorithms and com.ibm.jsse2.overrideDefaultProtocol can also affect the availability of protocols. For example, in IBM SDK, Java 8, jdk.tls.disabledAlgorithms disables SSLv3, TLSv1, TLSv1.1.

https://www.ibm.com/docs/en/sdk-java-technology/8?topic=suites-protocols

In z/OSMF 3.1 and 3.2, by default, the z/OSMF server uses the SSL protocol TLS for secure TCP/IP communications. As a result, the server can accept incoming connections that use SSL V3.0 and the TLS 1.0, 1.1, 1.2 and 1.3 protocols. Again, note that security and system properties such as jdk.tls.disabledAlgorithms and com.ibm.jsse2.overrideDefaultProtocol can also affect the availability of protocols. For example, in Semeru versions, jdk.tls.disabledAlgorithms disables SSLv3, TLSv1, TLSv1.1.

For example, in Semeru 11, the SunJSSE provider supports the protocol parameters listed in table 4-12 at https://docs.oracle.com/en/java/javase/11/security/oracle-providers.html#GUID-7093246A-31A3-4304-AC5F-5FB6400405E2__SUNJSSE_CIPHER_SUITES.

In IBM® Semeru Runtime Certified Edition for z/OS®, versions 11 and 17, the Transport Layer Security (TLS) protocol defaults to version 1.3 (TLSv1.3). If an RSA key is used, TLSv1.3 protocol requires handshake messages to be signed with an RSASSA-PSS signature. No other signature schemes are accepted. 

In the IBM SDK, Java™ Technology Edition, version 8.0.8.5, and Semeru Runtime Certified Edition for z/OS, versions 11.0.19.0 and 17.0.7.0, the use of RSASSA-PSS is enforced by the IBMJCECCA provider by validating that an RSA private key in PKDS format has the RSASSA-PSS parameter specification. This validation results in a limitation where RSA keys generated by using the RACF GENCERT command are rejected for TLSv1.3, because the keys do not contain the RSASSA-PSS parameter specification.

https://www.ibm.com/support/pages/node/7028845

Setting the TLS Version in z/OSMF

It is possible to force z/OSMF to use a particular TLS protocol. To do so, indicate which protocol is to be used by specifying it in an editable file local_override.cfg (EBCDIC). The override file is read during z/OSMF server initialization, and its values override the IBM® defaults for the z/OSMF configuration properties.

The following link goes over the steps to force a particular protocol.

https://www.ibm.com/docs/en/zos/2.5.0?topic=configurations-security-protocols-ciphers):

To specify a security protocol for z/OSMF connections, do the following:

1. Create an override file that is named local_override.cfg and store it in the z/OSMF configuration directory. For example: 
   /global/zosmf/configuration/local_override.cfg
2. In the override file, add an entry for the protocol that you want to use, as follows:
    IZU_SSL_PROTOCOL=<supportedprotocol>
   For example, to enable only TLS 1.2 connections, specify:
   IZU_SSL_PROTOCOL=TLSv1.2

Notice that the "v" in "TLSv1.2" is lower case.

z/OSMF and Ciphers

During the TLS handshake one of the most important steps is that a common cipher suite is present between the z/OSMF server and the client. Cypress suite has a unique name that is used to identify it and its components. For e.g., TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 means:

TLS

    defines the protocol that this cipher suite is for; it will usually be TLS.

ECDHE

    indicates the key exchange algorithm being used.

RSA

    authentication mechanism during the handshake.

AES

    session cipher.

128

    session encryption key size (bits) for cipher.

GCM

    type of encryption (cipher-block dependency and additional options).

SHA

    (SHA2) hash function. For a digest of 256 and higher. Signature mechanism. Indicates the message authentication algorithm which is used to authenticate a message.

256

    Digest size (bits)
https://en.wikipedia.org/wiki/Cipher_suite

Ciphers are introduced and deprecated periodically, and it is important to ensure there is a match between the ciphers supported by the client (typically the browser) and the ciphers supported by z/OSMF server.

List of supported cipher suites for Java 8 can be found here:

https://www.ibm.com/docs/en/sdk-java-technology/8?topic=suites-cipher

Cipher suites that are supported in Semeru 21 can be inferred from JSSE Cipher Suite Names section found here:

https://docs.oracle.com/en/java/javase/21/docs/specs/security/standard-names.html#jsse-cipher-suite-names

Advancements in cipher technology have significantly influenced the usage and selection of cipher types. RSA, once one of the most widely used key exchange algorithms, has largely been replaced by elliptic curve cryptography (ECC) methods such as ECDHE. Similarly, AES has superseded older encryption algorithms like DES, and GCM mode has replaced CBC mode for AES due to its superior performance and built-in authentication. GCM is also parallelizable, which further enhances efficiency.

More recently, TLS 1.3 has standardized cipher suites to a select few combinations of ECC and AES-GCM, including:

• TLS_AES_128_GCM_SHA256
• TLS_AES_256_GCM_SHA384
• TLS_CHACHA20_POLY1305_SHA256
• TLS_AES_128_CCM_SHA256
• TLS_AES_128_CCM_8_SHA256

This standardization has significantly narrowed the list of usable ciphers in TLS 1.3. For example, breaking down TLS_AES_128_GCM_SHA256:

• TLS – Indicates that TLS 1.3 is being used
• AES_128 – Advanced Encryption Standard with a 128-bit key
• GCM – Galois/Counter Mode, which encrypts data and provides an authentication tag
• SHA256 – Secure Hash Algorithm used for key derivation and authentication

Unlike TLS 1.2, TLS 1.3 cipher suites do not include authentication or key exchange algorithms. Instead, these components are negotiated separately:

• Key exchange (e.g., ECDHE) is transmitted during the ClientHello/ServerHello handshake and is built into the TLS protocol.
• Authentication (e.g., RSA) is determined by the certificate used and is also negotiated independently.

This separation allows for a reduced number of cipher suites while maintaining flexibility and security.

Setting or disabling Ciphers in z/OSMF

If you do not want to use the cipher order of precedence determined by the default z/OSMF providers list, you can force a particular set of cipher suites to be used for communication with z/OSMF.  

To specify a cipher or list of ciphers for z/OSMF server, use the IZU_CIPHERS_LIST statement in local_override.cfg file, this example specifies two ciphers:

IZU_CIPHERS_LIST=”SSL_RSA_WITH_3DES_EDE_CBC_SHA

TLS_RSA_WITH_AES_128_CBC_SHA”

z/OSMF requires local_override.cfg should contain a blank line at the end of the file. Therefore, a blank line needs to be inserted following the last statement in this override file for the overrides to take effect successfully. 

You can also disable a specific cipher or a list of ciphers from being used. In the following example, TLS_CHACHA20_POLY1305_SHA256 cipher is disabled.

Create /global/zosmf/configuration/local_override.cfg file (EBCDIC) with same owner and permissions as /global/zosmf/configuration/active_configuration.cfg if it does not already exist.
In it, add:

JVM_OPTIONS='-Djava.security.properties=/global/zosmf/configuration/jvm.security.ov'

 Note: Again, the file must end with a blank line.

Copy /usr/lpp/zosmf/defaults/servers/zosmfServer/jvm.security.override.properties to /global/zosmf/configuration/jvm.security.ov.

Find java.security file.
For Semeruxx:      /usr/lpp/java/Jxx.0_64/conf/security/java.security
Ex Semeru21:       /usr/lpp/java/J21.0_64/conf/security/java.security

Find the jdk.tls.disabledAlgorithms statement in the java.security file.

Semeru 21 java.security file contains:
jdk.tls.disabledAlgorithms=SSLv3, TLSv1, TLSv1.1, DTLSv1.0, RC4, DES, \
   MD5withRSA, DH keySize < 1024, EC keySize < 224, 3DES_EDE_CBC, anon, NULL, \
   ECDH

Copy the entire jdk.tls.disabledAlgorithms statement.
Replace everything in /global/zosmf/configuration/jvm.security.ov with what you copied.

So, /global/zosmf/configuration/jvm.security.ov might look like:

jdk.tls.disabledAlgorithms=SSLv3, TLSv1, TLSv1.1, DTLSv1.0, RC4, DES, \

   MD5withRSA, DH keySize < 1024, EC keySize < 224, 3DES_EDE_CBC, anon, NULL, \

   ECDH
Finally, append TLS_CHACHA20_POLY1305_SHA256 to it.
 /global/zosmf/configuration/jvm.security.ov should look like:

jdk.tls.disabledAlgorithms=SSLv3, TLSv1, TLSv1.1, DTLSv1.0, RC4, DES, \

   MD5withRSA, DH keySize < 1024, EC keySize < 224, 3DES_EDE_CBC, anon, NULL, \

   ECDH, TLS_CHACHA20_POLY1305_SHA256

z/OSMF and Certificates

There are a few different scenarios that have different steps for configuring certificates so refer to the documentation and decide which scenario best fits your system.

https://www.ibm.com/docs/en/zos/3.2.0?topic=configurations-configuring-zosmf-server-certificate-key-ring 

Beginning with PH58796, WebSphere Liberty performs hostname verification on SSL certificates. When an interim fix or fix pack (24.0.0.9) containing PH58796 is applied, the Liberty runtime automatically performs additional validation of certificates. This means that when Liberty is acting as a client connecting to an outbound server, the runtime now checks to make sure that the hostname value from the server certificate's Subject Alternative Name (SAN) or Common Name (CN) matches the hostname value used when establishing the connection.

https://www.ibm.com/support/pages/hostname-verification-liberty-zos

Temporary Workaround:

Copy the file server_override.xml from <product_dir>/defaults/servers/zosmfServer/  to <user_dir>/configuration. By default, product_dir = /usr/lpp/zosmf. By default, user_dir = /global/zosmf.

In <user_dir>/configuration/server_override.xml, replace everything with:

<server>

<ssl id="izuSSLConfig" keyStoreRef="defaultKeyStore" clientAuthenticationSupported="${izu.ssl.client.auth.supported}" sslProtocol="${izu.ssl.Protocol}" enabledCiphers="${izu.ciphers.list}" verifyHostname="false" />

</server>

Note, the server certificate needs to be connected to the keyring with USAGE type PERSONAL even if it is a SITE cert.

z/OSMF certificates cannot have DSA key type if TLS1.3 is used as DSA (DSS) public key cannot be used for TLS1.3 server authentication. DSA (finite-field DSS) was left out of TLS 1.3, so a certificate whose public key is DSA will not be accepted for TLS 1.3.

Also, as mentioned previously, if z/OSMF certificate uses an RSA key and if TLSv1.3 is used for connection, then the signing algorithm signature scheme needs to be RSASSA-PSS.