IBMCA-PROVIDER(5)

NAME
IBMCA-PROVIDER - IBMCA-PROVIDER is an OpenSSL provider that uses the libica library under s390x to accelerate cryptographic operations.

DESCRIPTION
IBMCA-PROVIDER accelerates cryptographic operations of applications that use OpenSSL. The provider can be configured by the OpenSSL configuration file.

The IBMCA-PROVIDER links the libica-cex library that can accelerate RSA, EC, and DH operations. Other (e.g. symmetric or digest) operations are not supported by the IBMCA-PROVIDER. Those are provided by the OpenSSL default provider (or others). Operations such as the AES cipher, as well as digest oprations are accelerated by CPACF by the OpenSSL default provider already. There is no need to use another provider for accelerating those.

  openssl.cnf
The OpenSSL configuration file can have a section for the IBMCA provider. This section includes the identity (i.e. name) of the provider (i.e. ibmca), the module implementing the provider (ibmca-provider.so), provider parameters, and if it is to be activated automatically. For a description of the provider parameter, see below.

Additionally, the OpenSSL configuration file can have a alg_section section. There, the default property query can be specified. To prefer using the IBMCA provider, but fall back to other providers (i.e. the default provider) specify:

default_properties = ?provider=ibmca.

OPTIONS

  openssl.cnf
Options for the IBMCA provider section in openssl.cnf:

identity = ibmca
    Set the name of the IBMCA provider. 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 config file is used, e.g. for an entry like ibmca_provider = ibmca_sect in the provider section, the name would be ibmca_provider.

module = ibmca-provider.so
    Set the name and optionally the path to the IBMCA provider shared object file allowing OpenSSL to find the file. Usually, providers are loaded from the OpenSSL MODULESDIR. Use openssl version -m to display the MODULESDIR used by OpenSSL. Set environment variable OPENSSL_MODULES to override the OpenSSL modules directory (ignored in set-user-ID and set-group-ID programs).

activate = 1
    OpenSSL will activate the provider if this option is set to 1.

algorithms = ALL | mechanisms
    Redirect all cryptographic operations through the provider or disable types of mechanisms that the provider supports. If ALL is not used, the algorithms consist of a comma separated list of mechanisms : RSA | EC | DH. If this option is not specified, ALL is the default.

debug = yes | no | stderr
    Enables debug output for the IBMCA provider. If this option is not specified, no debuging output is produced. If debug = stderr is specified, debugging messages are printed to stderr. Otherwise the debug output is written into a trace file in [/usr/local]/var/log/ibmca/trace-<provider-name>.<pid>, where <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.

fips = yes | no
    Enables FIPS mode for the IBMCA provider. If FIPS is enabled, it is ensured that the libica-cex library is built with FIPS enabled, and the system is running in FIPS mode. If that's 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 if the libica-cex library is built with FIPS enabled, and 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 algorithm with fips=yes, thus the IBMCA algorithms may be fetched using a property query string containing fips=yes.

    Note: The IBMCA provider is currently not FIPS certified. It does not itself perform any FIPS self tests nor an integrity check which would be required to be FIPS certifiable. It is only ensured that libica-cex library has successfully performed its self tests and integrity checks when FIPS mode is enabled. If you do not want that the IBMCA provider is used for property queries that include fips=yes, then disable FIPS mode of the IBMCA provider by setting fips = no in the provider configuration.

fallback-properties = property-query-string
    A property query string that is used to fetch algorithms for fallback purposes. Fallbacks take place when the libica-cex library does not support a certain key size or EC curve, or if the libica-cex 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-provider-name>[,fips=yes]. Clause fips=yes is included if FIPS mode is enabled for the IBMCA provider (either explicitly configured or due to auto-detection). Note that the IBMCA provider itself can not be used as fallback provider. Thus, the fallback property query string must either select a certain provider explicitly (e.g. 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).

ENVIRONMENT

IBMCA_DEBUG
    If $IBMCA_DEBUG is set to stderr debug output to stderr for the IBMCA provider is enabled. If it is set to on the debug output is written into a trace file in [/usr/local]/var/log/ibmca/trace-<provider-name>.<pid>, where <pid> is the process ID of the current process.

SEE ALSO
provider(1) config(5)