Features of the IBMCA engine

The IBMCA engine is an OpenSSL engine that uses the libica library to accelerate cryptographic clear key operations.

The engine can be configured for dynamic engine loading in the OpenSSL configuration file openssl.cnf (see Configuring OpenSSL to use the IBMCA engine).

Note: Symmetric algorithms, hash algorithms (digests), and elliptic curve algorithms are already accelerated by OpenSSL itself using CPACF. Therefore, do not accelerate them using the IBMCA engine. This will actually make them slower.

If installed and configured, OpenSSL does not perform the encryption requests by itself, but passes them to the IBMCA engine which in turn uses libica to handle the requests. The libica library is aware of which algorithms are supported via the underlying hardware (CPACF or cryptographic adapter, if installed and available). If an algorithm is supported by the underlying hardware, libica passes the request to the cryptographic hardware. If an algorithm is not supported by the underlying hardware, libica versions earlier than 4.0 execute the requests in software as an own fallback or use the OpenSSL library.

Since libica 3.8.0, there are two variants of the library module. The original libica.so module contains all features of the libica library as documented in the libica Programmer's Reference. It is the default library and is used by OpenSSL if the IBMCA engine is configured in the OpenSSL configuration file. If you build the IBMCA engine from the source, you can, however, specify the build time configuration switch --with-libica-cex. In that case, the second variant libica-cex.so becomes the default library. Thus, if both variants of the library are installed on a system, you can configure OpenSSL to use either of these two variants.

Applications that load the IBMCA engine can optionally send a control command to the engine, before the engine is initialized. For example, you can issue a control command in the openssl.cnf configuration file before the line init = 1. Control commands are key value pairs. The value can be a string, a numeric integer or be null.

Excerpt from an OpenSSL configuration file: The following sample shows the libica control command, specifying to use the libica.so.4 module of libica version 4.x.


[engine_section]
ibmca = ibmca_section

[ibmca_section]
# The openssl engine path for ibmca.so.
# Set the dynamic_path to where the ibmca.so engine
# resides on the system.
dynamic_path = /usr/local/lib/ibmca.so
engine_id = ibmca
libica = libica.so.4
init = 1

For more information, read the engine(3) man page.

Supported algorithms

The IBMCA engine supports RSA, DH, DSA, ECDSA, ECDH, EdDSA, EdDH, and symmetric ciphers and hash (or digest) algorithms. Depending on the available cryptographic hardware and the used libica library variant, certain algorithms may or may not be supported.

As previously mentioned, symmetric ciphers, hash algorithms (digests), and elliptic curve algorithms are already accelerated by OpenSSL itself using CPACF. Therefore, do not accelerate them using the IBMCA engine. This will actually make them slower.

Software fallbacks with the IBMCA engine

If you use the IBMCA engine with a full libica library version older than 4.0, then libica provides SW fallbacks for most of the algorithms by invoking the respective OpenSSL function.

libica versions starting with 4.0, or the libica-cex variant of libica do no longer support SW fallbacks. So, if you use the IBMCA engine with a libica library version starting with 4.0, or the libica-cex variant of libica, the IBMCA engine provides SW fallbacks using OpenSSL algorithms for the following cryptographic processing:

The fallbacks are used in case where a key size (RSA, DH: > 4096 bits), or an elliptic curve is not supported by the used libica library, or when the libica library fails to perform the operation (for example, a cryptographic adapter went offline during an operation).

All other algorithms supported by the IBMCA engine do not provide SW fallbacks.