What is IBMJCEHYBRID?

We are proud to showcase one of our providers, IBMJCEHYBRID. So what is this provider? Well, the IBM Java Cryptography Extension Hybrid Provider (IBMJCEHYBRID) is a JCE security provider developed by IBM that routes application requests for cryptography to different JCE providers, depending on their availability. We designed IBMJCEHYBRID to be unique by enabling applications that rely on cryptographic hardware to seamlessly fail over to another JCE provider, ensuring uninterrupted cryptographic operations when the hardware becomes unavailable. We strive to make using IBMJCEHYBRID a versatile experience for our users by using multiple providers and choosing the most suitable provider for the service that is needed.

Features of the IBMJCEHYBRID provider

We wanted IBMJCEHYBRID to provide support for all features that the IBMJCECCA (IBM Java Cryptography Extension Common Cryptographic Architecture) provider supports which consists of: cryptographic ciphers, signatures, & message digests, along with key generation, key management, and storage capabilities. See this link for the full table on the capabilities that are supported by IBMJCEHYBRID from IBMJCECCA.

Why use IBMJCEHYBRID?

To know more about each feature of IBMJCEHYBRID, click on this link. And to learn more about IBMSecureRandom, please read here.

How to enable and configure IBMJCEHYBRID

In order for us to use IBMJCEHYBRID, first download IBM Semeru Runtime Certified Edition for z/OS, Version 17+ and install it onto your z/OS system. You must then edit the java.security file so that IBMJCEHYBRID appears first in the JCE provider list. Here’s an example…

security.provider.1=IBMJCEHYBRID
security.provider.2=IBMJCECCA
security.provider.3=OpenJCEPlus
security.provider.4=IBMZSecurity
security.provider.5=SUN
security.provider.6=SunRsaSign
security.provider.7=SunEC
security.provider.8=SunJSSE
security.provider.9=SunJCE
.
. (rest of list omitted)
.

Note: If IBMJCEHYBRID is not the first JCE provider in the JVM provider list then a cryptographic request might be routed to a different JCE provider instead of IBMJCEHYBRID. This results in IBMJCEHYBRID not having control and cannot provide the proper assistance on the routing or failover for the request.

Examples

The diagram below demonstrates the flow of what occurs when IBMJCEHYBRID is invoked as the first provider on the list. 

We shall look at the following scenarios that illustrate the failover service that can be provided by IBMJCEHYBRID based off the diagram above: 

Example 1: Multi-Provider Failover

• JCE providers in the JVM security list are as follows:

1. IBMJCEHYBRID

2. IBMJCECCA

3. IBMZSecurity

4. OpenJCEPlus

• Scenario: An application requests a serviceType.algorithm supported by IBMJCECCA, IBMZSecurity, and OpenJCEPlus. The application does not specify a provider on getInstance().

• Flow:

• IBMJCEHYBRID has priority and routes the request to IBMJCECCA.

• If IBMJCECCA is unable to process the request it will throw an exception, and IBMJCEHYBRID will catch the exception and attempt to failover to the next provider, IBMZSecurity.

• If IBMZSecurity is also unable to process the request it too will throw an exception, and IBMJCEHYBRID will catch that exception and attempt to failover to OpenJCEPlus.

Example 2: Routing to OpenJCEPlus when IBMJCECCA lacks support

• JCE providers in the JVM security list are as follows:

1. IBMJCEHYBRID

2. IBMJCECCA

3. OpenJCEPlus

• Scenario: An application requests a serviceType.algorithm supported by OpenJCEPlus but not supported by IBMJCECCA. The application does not specify a provider on getInstance().

• Flow:

• IBMJCEHYBRID has priority and routes the request immediately to OpenJCEPlus due to IBMJCECCA not supporting the service.

• If OpenJCEPlus is unable to process the request it will throw an exception, and IBMJCEHYBRID will catch the exception and wrap it in an IBMJCEHYBRIDException and throws it to the application.

Example 3: Multi-Provider Failover with Exception Wrapping

• JCE providers in the JVM security list are as follows:

1. IBMJCEHYBRID

2. IBMJCECCA

3. OpenJCEPlus

• Scenario: An application requests a serviceType.algorithm supported by both IBMJCECCA and OpenJCEPlus. The application does not specify a provider on getInstance().

• Flow:

• IBMJCEHYBRID has priority and routes the request to IBMJCECCA.

• If IBMJCECCA is unable to process the request it will throw an exception, and IBMJCEHYBRID will catch the exception and attempt to failover to OpenJCEPlus.

• If OpenJCEPlus is unable to process the request it will throw an exception, and IBMJCEHYBRID will catch the exception and wrap both exceptions from IBMJCECCA and OpenJCEPlus in an IBMJCEHybridException and throws it to the application.

Example 4: Runtime insertion of IBMJCEHYBRID

• JCE providers in the JVM security list are as follows:

1. IBMJCECCA

2. OpenJCEPlus

• Scenario: An application (to programmatically insert a security provider at runtime) calls Security.insertProviderAt(new com.ibm.crypto.ibmjcehybrid.provider.IBMJCEHYBRID, 1) and then requests a serviceType.algorithm supported by both IBMJCECCA and OpenJCEPlus. The application does not specify a provider on getInstance().

• Flow:

• IBMJCEHYBRID has priority and routes the request to IBMJCECCA.

• If IBMJCECCA is unable to process the request it will throw an exception, IBMJCEHYBRID will catch the exception and attempt to failover to OpenJCEPlus.

Example 5: Runtime Insertion of another Provider

• JCE providers in the JVM security list are as follows:

1. IBMJCEHYBRID

2. IBMJCECCA

3. OpenJCEPlus

• Scenario: An application calls Security.insertProviderAt(new mypkg.MyProvider, 1) and then requests a serviceType.algorithm supported by MyProvider, IBMJCECCA, and OpenJCEPlus. The application does not specify a provider on getInstance().

• Flow:

• MyProvider has priority and is unable to process the request and throws an exception.

• The exception is then passed back to the application (Without IBMJCEHYBRID, no failover can be executed.)

For more examples, please see this List of Examples.

Conclusion

By using IBMJCEHYBRID in our applications, we can use JCE providers that have platform dependencies without needing to include complex errors handling for when the platform’s cryptographic features are not available. This provider was specifically designed with this feature, giving users the flexibility to use multiple providers on a variety of services that they may need. Give it a go!

How to obtain IBMJCEHYBRID

IBMJCEHYBRID is included in the IBM Semeru Runtime Certified Edition for z/OS download. Please follow the links below to download the IBM Semeru JDK onto your own machine.

How to obtain IBM Semeru Runtime Certified Edition for z/OS?
IBM Semeru Runtime Certified Edition for z/OS is available for zero license charge through Shopz SMP/E, or you can download the non-SMP/E here. The subscription and service number is 5655-I48.

Supporting Links:
IBM Semeru Runtime Certified Edition for z/OS product page
For additional information on installation, troubleshooting and support please visit IBM Documentation.