Configuring OpenSSL to use the IBMCA engine
The OpenSSL configuration file can have an IBMCA section which only includes configuration options for 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,
ALL
is the default. However, do not use ALL with IBMCA, because for example, depending on the hardware level (IBM z15™), 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,algorithms = RSA,DH,DSA
.- 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 byCIPHERS
,DIGESTS
,EC
, andPKEY
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 thedefault_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