Configuring OpenSSL to use the IBMCA provider

You can explicitly load the IBMCA provider by your application, but in most cases it is automatically and transparently loaded, if your application uses OpenSSL. In such cases you configure the IBMCA provider in the OpenSSL configuration file (for example, openssl.cnf).

$ openssl version -d
OPENSSLDIR: "/etc/pki/tls"

Alternatively, set environment variable OPENSSL_CONF to point to the configuration file to use. To automatically load the IBMCA provider for OpenSSL applications, configure it in the OpenSSL configuration file. Add an IBMCA provider section to the OpenSSL configuration file. In our example from Example OpenSSL configuration file, this section is called [ibmca_sect]. The OpenSSL provider section (in our example called [provider_sect]) must point to this IBMCA provider section [ibmca_sect] where the name of the IBMCA provider is specified with the identity = ibmca entry. In addition, section [ibmca_sect] points to the module implementing the provider (ibmca-provider.so), to other provider parameters, and specifies whether the IBMCA provider is to be activated automatically. All section names shown in Example OpenSSL configuration file are examples only. You can choose your own names.

Besides the IBMCA provider another provider (for example, the OpenSSL default provider in [default_sect]) must also be configured to be used for those algorithms which are not supported by the IBMCA provider.

Additionally, the OpenSSL configuration file can have an alg_section. There, the section may have an entry that in turn points to a section defining the default property query string. To prefer using the IBMCA provider, but use other configured providers for algorithms not configured or supported by the IBMCA provider, specify, for example:

alg_section = evp_properties
...
...
[evp_properties]
default_properties = ?provider=ibmca

Configure the IBMCA provider in the IBMCA provider section of the OpenSSL configuration file using the following options. Also, refer to the OpenSSL configuration file man page.

identity = <name>

Set the name of the IBMCA provider:

identity = ibmca

The name of the provider is used in the property query string used to fetch the provider for an operation. If no identity is specified, the name from the provider section of the OpenSSL configuration file is used, for example, for an entry like ibmca_provider = ibmca_sect in the provider section ([provider_sect]), the name would be ibmca_provider (see Example OpenSSL configuration file).

Normally the name should always be ibmca, but you can also choose another name. You can also define two sections, that is, two instances, of the IBMCA provider with different names (and for example, differently configured algorithms). Then the desired IBMCA provider instance can be chosen by an application for an operation using a property query.

module = <shared_library>

Set the name and optionally the path to the IBMCA provider shared object file allowing OpenSSL to find the file. The IBMCA provider is contained in ibmca-provider.so, so specify: module = ibmca-provider.so.

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

activate = 1

OpenSSL activates the provider if this option is set to 1.

algorithms = ALL | <algorithms>

Redirect all cryptographic operations through the provider or disable types of mechanisms that the provider 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® 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. The IBMCA provider supports RSA, DH, and EC. Example:

algorithms = RSA,DH

debug = yes | no | stderr

Enables debug output for the IBMCA provider. If this option is not specified, no debugging output is produced. If debug = stderr is specified, debugging messages are printed to stderr. If debug = yes is specified, the debug output is written into a trace file in <debug-path>/trace-<provider-name>.<pid>, where <debug-path> is the path name of a directory to where the debug files are written (default: /tmp), <provider-name> is the name of the IBMCA provider from the identity option, and <pid> is the process ID of the current process. You can also enable debugging by setting the environment variable IBMCA_DEBUG to on or stderr. If this option is not specified, no is the default.

debug-path = /dir/to/debug/directory

Sets the directory path to where debug files are written when debug is enabled via debug = yes or via environment variable IBMCA_DEBUG=on. You can also set the debug path by setting the environment variable IBMCA_DEBUG_PATH to the directory path. Ensure that the user under which the application that uses the IBMCA provider runs, has write access to that directory. If this option is not specified, the default debug path is /tmp.

fips = yes | no

Enables FIPS mode for the IBMCA provider. If FIPS is enabled, it is checked whether the libica library is built with FIPS enabled, and the system is running in FIPS mode. If this is not the case, the IBMCA provider initialization fails, and a syslog message is issued. If the fips option is not specified, it is auto-detected whether the libica library is built with FIPS enabled, and whether the system is running in FIPS mode. If both is true, then the FIPS mode is enabled for the IBMCA provider. If FIPS is enabled (either explicitly configured or due to auto-detection), the IBMCA provider registers its algorithms with fips=yes. Thus the IBMCA algorithms may be fetched using a property query string containing fips=yes.

Note: Disable the FIPS mode of the IBMCA provider by setting fips=no in the provider configuration. The IBMCA provider is currently not FIPS-certified. It does not perform any FIPS self-tests itself nor an integrity check which would be required to be FIPS-certified. It is only checked whether libica library has successfully performed its self-tests and integrity checks when FIPS mode is enabled.

fallback-properties = <property-query-string>

A property query string that is used to fetch algorithms for fallback purposes. Fallbacks take place when the libica library does not support a certain key size or EC curve, or if the libica library fails to perform a crypto operation for whatever reason. If this option is not specified, a fallback property query string is built automatically as follows:

provider!=<ibmca-providername>[,fips=yes]

Clause provider!=ibmca-provider means that OpenSSL shall take the fallback algorithms from any provider except the IBMCA provider.

Clause fips=yes is included if FIPS mode is enabled for the IBMCA provider (either explicitly configured or due to auto-detection). The IBMCA provider itself can not be used as fallback provider. Thus, the fallback property query string must either select a certain provider explicitly (for example, provider=default), or must exclude the IBMCA provider (provider!=<ibmca-provider-name>). If FIPS mode is enabled for the IBMCA provider, the fallback provider should also be FIPS enabled. Include fips=yes into the fallback property query string, or explicitly select the FIPS provider (provider=fips).

For more information on property queries, refer to the OpenSSL Property man page.

Example OpenSSL configuration file

openssl_conf = openssl_def

[openssl_def]
providers = provider_sect
alg_section = evp_properties

[provider_sect]
default = default_sect
ibmca_provider = ibmca_sect

[default_sect]
activate = 1

[ibmca_sect]
identity = ibmca
module = ibmca-provider.so
activate = 1
fips = no
#debug = yes
algorithms = RSA,DH
# Algorithm EC omitted for systems starting with IBM z15
#fallback-properties = provider=default

[evp_properties]
default_properties = ?provider=ibmca

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