Features of the IBMCA provider

Edit online

The IBMCA provider implements a dynamically loadable extension to OpenSSL to accelerate clear key cryptographic operations. In contrast to the IBMCA engine, which routes cryptographic operations to the libica.so library file, the IBMCA provider routes operations to the library module libica-cex.so of libica version 4.0 or later, which performs the operations on cryptographic adapters configured in either accelerator mode or CCA mode.

Note: You can also build the IBMCA provider to use the fully functional libica module of libica version 4.0 or later (see Installing IBMCA from the source package). Also, distributors may ship libica version 4.0 built as libica.so.

The libica-cex library is a variant of the libica module and does not provide CPACF functionality. The IBMCA provider as default requires the libica-cex library of libica version 4.0 or later. Also, software fallbacks are no longer provided with libica version 4.0 or later.

When configured, the IBMCA provider is transparently used by applications using OpenSSL to perform the cryptographic operations registered with the IBMCA provider.

Supported algorithms

During IBMCA provider initialization, the used variant of the libica library is queried to find out which algorithms are supported. The IBMCA provider registers itself only for those algorithms, that are supported by the used libica library variant and which are enabled per configuration. Thus, when no suitable cryptographic adapters are available during initialization, the IBMCA provider does not register itself for any algorithm.

The IBMCA provider supports RSA, ECC, and DH algorithms. Other algorithms, such as symmetric ciphers or digests are not supported, because OpenSSL internally uses CPACF to accelerate those algorithms (with the exception of DES/TDES). The same is the case for Ed25519, Ed448, X25519, and X448, those are also accelerated by using CPACF internally by OpenSSL (see also Table 1 ). Other asymmetric algorithms like DSA are not supported by the IBMCA provider. Any algorithm not supported by the IBMCA provider (either because the IBMCA provider generally does not support the algorithm, or because no suitable cryptographic adapter is available, or because the algorithm has not been enabled in the IBMCA provider configuration) falls back to other configured OpenSSL providers. Dependent on the OpenSSL configuration, this can either be the OpenSSL default provider, or any other OpenSSL or custom provider.

Software fallbacks with the IBMCA provider

Software fallbacks are no longer provided by default with libica starting with version 4.0. Instead, the IBMCA provider itself implements software fallbacks for all algorithms it supports. These fallbacks are based on the OpenSSL software implementation using the default provider, or whatever provider is configured additionally to the IBMCA provider.

You can use option fallback-properties in the OpenSSL configuration file to set a query string for the fallback provider (see Configuring OpenSSL to use the IBMCA provider). If no fallback-properties option is set, the fallback algorithms are fetched using a property query similar to the following: 
provider!=<IBMCA-provider-name>
Or, if FIPS mode is enabled: 
provider!=<IBMCA-provider-name>,fips=yes
For more information on property queries, refer to the OpenSSL Property man page.

This way, any other configured provider, except the IBMCA provider, that supports the desired algorithm is used. In most cases this will be the OpenSSL default provider, or the OpenSSL FIPS provider (for FIPS mode). If no other provider is configured, then no software fallbacks are available.

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

The IBMCA provider still registers itself only for those algorithms, that the libica library reports to be supported at provider startup. If no cryptographic adapter is available during startup, and therefore, libica reports no algorithms to be supported, then the IBMCA provider does not register itself for any algorithm, even if it would have a software fallback implemented.

Debugging facilities

There is an environment variable IBMCA_DEBUG that you can set for obtaining debug information when using the IBMCA provider. For more information, read Troubleshooting and debugging.

APIs for message signing and verification

Starting with OpenSSL 3.4.0 and the IBMCA provider 2.5.0, the following APIs are supported for composite hash-then-sign algorithms:

  • EVP_PKEY_sign_message_init()
  • EVP_PKEY_sign_message_update()
  • EVP_PKEY_sign_message_final()
  • EVP_PKEY_verify_message_init()
  • EVP_PKEY_verify_message_update()
  • EVP_PKEY_verify_message_final()
  • EVP_PKEY_sign_init_ex2()
  • EVP_PKEY_verify_init_ex2()

Examples for supported composite hash-then-sign algorithms are ECDSA-SHAxxx or ECDSA-SHA3-xxx algorithms, or RSA-SHAxxx, or RSA-SHA3-xxx algorithms.

The advantage of using EVP_PKEY_sign/verify_message_<ttt>() functions is that digesting and signing or verifying is performed in one step by one provider.

Furthermore, using EVP_PKEY_sign_init_ex2() followed by EVP_PKEY_sign(), or EVP_PKEY_verify_init_ex2() followed by EVP_PKEY_verify(), you can perform a sign or verify operation on a pre-computed message digest with a composite hash-then-sign algorithm.

Using RSA keys

When using RSA keys, you need to observe the following considerations:

  • Support for parameter rsa-derive-from-pq for key import with the IBMCA provider version 2.5.0:

    When importing a private RSA key from parameters, allow that only private Chinese-Remainder Theorem (CRT) key components rsa-factor1 (p), rsa-factor2 (q), as well as the public key components n and e are available in the parameters, when also parameter rsa-derive-from-pq with a non-zero value is contained. In this case, the other CRT components are calculated to form a complete CRT key.

  • Parameter rsa-derive-from-pq is available since OpenSSL 3.3.

Implicit rejection for RSA PKCS#1 v1.5 padding

The IBMCA provider supports the so-called implicit rejection. This feature returns a pseudo random message instead of an error in case of an RSA padding check error. This helps applications to better handle such error situations and prevents them from being vulnerable by timing attacks, such as the Bleichenbacher attack.

This feature is enabled by default if compiled against an OpenSSL upstream version starting with 3.2.0.