Decide about the flavor of IBMCA

OpenSSL supports a plug-in mechanism that allows to provide alternative implementations of cryptographic methods. The plug-in mechanism supported by OpenSSL version 1.x.y is called engine. The plug-in mechanism supported by OpenSSL 3.0 and later is called provider.

For general details on engines, providers and their differences read Engines and providers or see the OpenSSL documentation. This topic informs you about the IBM-specific engine and provider for OpenSSL.

Engines and providers for IBM Z

Use the IBMCA provider starting with OpenSSL version 3.0 and use the IBMCA engine for any earlier OpenSSL version (1.x.y). Even though OpenSSL claims that engines can be used as deprecated plug-in mechanism for OpenSSL 3.0, the use of engines with OpenSSL later than version 1.1.1 is not recommended.

Applications with compiled-in OpenSSL support can enable the IBMCA provider or the IBMCA engine in the OpenSSL configuration file. However, do not use the IBMCA engine with OpenSSL 3.0 or later. Use the IBMCA provider instead. Sample OpenSSL configuration files (openssl.cnf.sample or openssl.cnf.provider.sample) are included in the package that you download from GitHub. See also Configuring OpenSSL to use the IBMCA provider.

In an IBM Z environment, you can install the IBMCA provider or the IBMCA engine, or both, and configure OpenSSL for dynamic engine or provider loading. In such cases, OpenSSL does not perform the encryption requests by itself, but passes them to the configured IBMCA module. IBMCA uses the libica library to handle the requests. The libica library is aware of which algorithms are supported via the underlying hardware (CPACF or cryptographic adapters, if installed and available). If an algorithm is supported by hardware, the libica library passes the request to the cryptographic hardware. If an algorithm is not supported by hardware, libica versions earlier than 4.0 execute the algorithm in software as a fallback. For information about SW fallbacks in libica versions starting with 4.0, see Software fallbacks with the IBMCA provider.

Note on terminology: As a default, the IBMCA provider is built against the libica-cex variant of the libica library, whereas the IBMCA engine per default is built against the full libica module variant of the libica library. However, you can also configure the IBMCA provider to utilize the full libica module or configure the IBMCA engine to utilize libica-cex. In cases, where differentiation between the variants of the libica library is of no importance, this publication just uses the term libica library to refer to either the full version or to the libica-cex variant.

Difference between the IBMCA provider and the IBMCA engine

The IBMCA engine performs acceleration of symmetric ciphers and hash functions on the CPACF and asymmetric algorithms on a cryptographic adapter. For elliptic curve cryptography using the full version of the libica library, starting with IBM z15™, processing is performed on CPACF instead off a cryptographic adapter for supported curves.

Symmetric ciphers and hash functions that are also implicitly accelerated by OpenSSL, are preferably performed by OpenSSL and should not be configured to be performed by the IBMCA engine. Therefore, in the OpenSSL configuration file, define only those algorithms that you want to be accelerated by the IBMCA engine, for example:

default_algorithms = RSA,DH,DSA

Refer to Table 1. Dependent on your hardware level, certain algorithms may or may not yet been accelerated by OpenSSL. Therefore, you may need to adjust the default_algorithms specification accordingly, for example, including or excluding ECC operations.

The IBMCA provider only performs asymmetric algorithms on a cryptographic adapter. However, only algorithms configured for the IBMCA provider are performed.