Configuring OpenSSL to use the IBMCA engine

The build process of the IBMCA engine produces a script called ibmca-engine-opensslconfig which can be used to update an existing OpenSSL configuration to enable the IBMCA engine. By default, this script is not automatically included with the package, but it is in the responsibility of the distributions whether to include it and if so, where to install it.

Configuration options for the IBMCA engine

You can specify the following options in the IBMCA section in file openssl.cnf. Also, refer to the OpenSSL configuration file man page.

dynamic_path = <path_to_ibmca.so>

Set the path to the IBMCA shared object file allowing OpenSSL to find the file.

Engines are usually loaded from the OpenSSL ENGINESDIR which was configured during OpenSSL build. You can use the command openssl version -e to display the OpenSSL ENGINESDIR setting. Alternatively, set environment variable OPENSSL_ENGINES to point to the directory where the engine is located. However, the setting of this environment variable is ignored, if a program trying to access the IBMCA engine is marked with access right flag setuid.

This option must appear before the init option described later in this list.

engine_id = <name>

Set the name of the engine. The default name is ibmca.

This option must appear before the init option described later in this list.

libica = libica-cex.so.4

If both variants of the libica library module (libica-cex.so or libica.so) are installed on a system, OpenSSL can be configured to use either of these two. For example, to use libica-cex.so.4 for the IBMCA engine, add the line libica = libica-cex.so.4.

If used, this option must be specified at the beginning.

init = 0 | 1

OpenSSL tries to initialize the engine if this option is set to 1. If set to 0, OpenSSL will not try to initialize the engine.

default_algorithms = ALL | <algorithms>

Redirect all cryptographic operations through the engine or redirect only certain types of operations that the engine supports. If this option is not specified, no algorithms are redirected to the engine. Do not use ALL with IBMCA, because for example, depending on the hardware level (IBM z15® or IBM® LinuxONE III), ECC is already accelerated implicitly by OpenSSL for certain curves (see Figure 1). Instead, use a comma-separated list for the required algorithms, for example,

default_algorithms = RSA,DH,DSA

You can specify the following values with the <algorithms> parameter:

• CIPHERS
• DH
• DIGESTS
• DSA
• EC
• PKEY
• PKEY_ASN1
• PKEY_CRYPTO
• RAND
• RSA

If you specify a list of algorithms to be enabled for the engine, all algorithms not specified in this list are performed by OpenSSL.

PKEY_ASN1 means ASN.1 conversion, printing, and information methods for a specific public key algorithm.

PKEY_CRYPTO means methods for a specific public key cryptographic algorithm. Those methods are usually used to perform different jobs, such as generating a key, signing or verifying, encrypting or decrypting.

Specifying PKEY achieves the same results as PKEY_ASN1 and PKEY_CRYPTO together. Therefore, with specifying PKEY, you achieve support for Edwards and Montgomery Curves (Ed25519 and Ed448 or X25519 and X448).

Only all CIPHERS or DIGESTS, or both can be deactivated or activated. Algorithms like AES can not be deactivated or activated independently.

For example:

default_algorithms = RSA,DH,DSA

Note: Algorithms denoted by CIPHERS, DIGESTS, EC, and PKEY are already accelerated by OpenSSL itself using CPACF. Therefore, do not accelerate them using the IBMCA engine. This will actually make them slower.

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 following example demonstrates the setup of the IBMCA engine using OpenSSL version 1.1 and the IBMCA package version 2.2.1. In older or newer versions the setup is different and can be performed by using helper scripts delivered with the package ( newer releases) or refer to the README and sample files in the package (older releases).

/usr/share/doc/openssl-ibmca/openssl.cnf.sample.s390x
#
# OpenSSL example configuration file. This file will load the IBMCA engine
# for all operations that the IBMCA engine implements for all apps that
# have OpenSSL config support compiled into them.
#
# Adding OpenSSL config support is as simple as adding the following line to
# the app:
#
# #define OPENSSL_LOAD_CONF     1
#
openssl_conf = openssl_def

[openssl_def]
engines = engine_section

[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.
engine_id = ibmca
dynamic_path = /usr/lib64/engines-1.1/ibmca.so
init = 1

...

default_algorithms = RSA,DH,DSA