IBMCA-PROVIDER(5)

📦 version 2.5.0, in opensuse-leap 16.0

💅 IBMCA-PROVIDER 💅

okay so this is the man page for IBMCA-PROVIDER(5) — section 5, system file formats, the whole vibe — and bestie, it's literally about an OpenSSL provider that uses the libica library under s390x to make cryptographic operations go zoom. 🏎️✨

🌸 NAME 🌸

IBMCA-PROVIDER — it's an OpenSSL provider that uses the libica library under s390x to accelerate cryptographic operations. that's the whole thing, she's an accelerator 💨

🦋 DESCRIPTION 🦋

IBMCA-PROVIDER speeds up cryptographic operations for applications that use OpenSSL. And the way you configure it? Through the OpenSSL configuration file, periodt. 🎀

IBMCA-PROVIDER links the libica-cex library, which can accelerate RSA, EC, and DH operations. Other stuff — like symmetric or digest operations — is not supported by IBMCA-PROVIDER, no cap. Those get provided by the OpenSSL default provider (or others). And here's the thing: operations like the AES cipher, plus digest operations, are already accelerated by CPACF via the OpenSSL default provider. So there's genuinely no need to pull in another provider for accelerating those — it's giving redundant 💀

🧚 openssl.cnf

The OpenSSL configuration file can have a section for the IBMCA provider. This section includes:

  • the identity (i.e. the name) of the provider (i.e. ibmca)
  • the module implementing the provider (ibmca-provider.so)
  • provider parameters
  • and whether it's to be activated automatically

for a description of the provider parameters, scroll down bestie, it's all there 💖

Additionally, the OpenSSL configuration file can have an alg_section section. That's where you can specify the default property query. And if you want to prefer using the IBMCA provider but fall back to other providers (i.e. the default provider), you specify:

default_properties = ?provider=ibmca.

slay. that little ? is doing so much work 🫶

✨ OPTIONS ✨

🎀 openssl.cnf

Options for the IBMCA provider section in openssl.cnf:

  • identity = ibmca — sets the name of the IBMCA provider. The provider's name is used in the property query string that fetches the provider for an operation. If no identity is specified, the name from the provider section of the OpenSSL config file is used — like, for an entry like ibmca_provider = ibmca_sect in the provider section, the name would be ibmca_provider. ikyk. 🧠✨
  • module = ibmca-provider.so — sets the name, and optionally the path, to the IBMCA provider shared object file, so OpenSSL can find it. Usually providers get loaded from the OpenSSL MODULESDIR. Use openssl version -m to display the MODULESDIR that OpenSSL is using. And you can set the environment variable OPENSSL_MODULES to override the OpenSSL modules directory — though heads up, it's ignored in set-user-ID and set-group-ID programs. 🙈
  • activate = 1 — OpenSSL will activate the provider if this option is set to 1. simple as that, she's awake 💅
  • 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.
Note: depending on the hardware level (IBM z15), EC is already accelerated implicitly by OpenSSL for certain curves. So do not accelerate EC using the IBMCA provider if you're on an IBM z15 or later — it would actually make it slower. not the glow-up you wanted 😭
  • debug = yes | no | stderr — enables debug output for the IBMCA provider. If this option isn't specified, no debugging 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 <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. 🐛✨
  • 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. It must be ensured that the user under which the application using the IBMCA provider runs has write access to that directory — fr fr, check your perms. 🙏 If this option isn't specified, the default debug path is /tmp.
  • fips = yes | no — enables FIPS mode for the IBMCA provider. If FIPS is enabled, it's ensured that the libica-cex library is built with FIPS enabled, and that 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 isn't specified, it's auto-detected whether the libica-cex library is built with FIPS enabled and whether the system is running in FIPS mode. If both is true, then 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, so 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's only ensured that the libica-cex library has successfully performed its self tests and integrity checks when FIPS mode is enabled. If you do not want the IBMCA provider to be 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 used to fetch algorithms for fallback purposes. Fallbacks take place when the libica-cex library doesn't 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 isn't specified, a fallback property query string is built automatically as follows: provider!=<ibmca-provider-name>[,fips=yes]. The 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 — so 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's set to on, 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. 🍓
  • IBMCA_DEBUG_PATH — sets the directory path to where debug files are written when debug is enabled via the debug = yes configuration option or via environment variable IBMCA_DEBUG=on. It must be ensured that the user under which the application that uses the IBMCA provider runs has write access to that directory. (yes, saying it twice, because it matters 💅)

💜 SEE ALSO 💜

provider(1) config(5)

and that's the page bestie 🫶 it's from 2022, dated February, brought to you by IBM — go accelerate something iconic 💖✨🎀

📦 where this page comes from