Quick decision: OpenSSL on IBM Z and LinuxONE out of the box or with customized extensions

You can exploit the combination of IBM Z cryptographic hardware acceleration and OpenSSL without any configuration - implicitly out of the box for mainly symmetric ciphers and digests, as well as for some asymmetric cryptography (ECC with certain curves), and depending on the hardware level. If your system has access to a Crypto Express adapter in accelerator or CCA mode, you can configure OpenSSL to additionally accelerate further asymmetric cryptography (RSA, ECC, DH). This document informs about the implicit acceleration as well as about how to configure OpenSSL for special requirements.

This publication offers two decision paths to find your adequate usage of OpenSSL on Linux on IBM Z and LinuxONE together with hints how to navigate to the pertaining information in this document.

  1. You can use Figure 1 to check your main cryptographic processing type and then determine the required hardware and software prerequisites: Decide according to what you want to do
  2. You can check your available OpenSSL environment and then find out what you can do with it: Decide according to what you have
Note on terminology:

Certain terms are central for this publication:

Decide according to what you want to do

Select the main characteristics of your cryptographic workload from Figure 1 and find out how to use OpenSSL.

A note on workload characteristics:

Secure communication protocols like TLS, SSH, or IPSec comprise a handshake part and a payload transmission part. Only the handshake part uses asymmetric ciphers. Therefore, workloads using such network communication protocols make considerable use of asymmetric ciphers (RSA, DH, ECDSA, ECDH, DSA) if the workload opens many connections each of which transfers only a small amount of payload data. In contrast, for a connection used to transfer large amounts of data, the cost of the handshake has little impact on the overall connection cost and should not be considered to make considerable use of asymmetric ciphers.

Figure 1. Decision tree
Decision tree

The diagram from Figure 1 shows the following options:

  • For considerable usage of RSA or DH with a CEX accelerator or CCA coprocessor:
    • When using OpenSSL 1.1.1 or earlier, then configure the IBMCA engine to use RSA or DH or both.
    • When using OpenSSL 3.0 or later, then configure the IBMCA provider to use RSA or DH or both.
    • Without available CEX accelerator or CCA coprocessor, use OpenSSL out of the box.

    Find the required information in topics:

  • For considerable usage of ECC:
    • For considerable usage of P-256, P-384, P-512, Ed25519, X255219, Ed448, X448 curves:
      • When working on IBM z15™ or LinuxONE II or later hardware, then use the default: OpenSSL out of the box.
      • When working on hardware earlier than IBM z15 or LinuxONE II with a CCA coprocessor:
        • When using OpenSSL up to version 1.1.1, then configure the IBMCA engine to use ECC.
        • When using OpenSSL 3.0 or later, then configure the IBMCA provider to use ECC.
    • For considerable usage of Brainpool curves with a CCA coprocessor :
      • When using OpenSSL up to version 1.1.1, then configure the IBMCA engine to use ECC.
      • When using OpenSSL 3.0 or later, then configure the IBMCA provider to use ECC.
    • For other usages of ECC, use the default: OpenSSL out of the box.

    Find the required information in topics:

  • For considerable usage of symmetric ciphers and digests, use the default: OpenSSL out of the box.

    Find the required information in OpenSSL on IBM Z - out of the box.

  • For considerable usage of DSA:
    • When using OpenSSL 1.1.1 or earlier, then configure the IBMCA engine to use DSA.
    • When using OpenSSL 3.0 or later, then use the default: OpenSSL out of the box, because the IBMCA provider does not support DSA.

    Find the required information in topics:

Find further information that you may need or find helpful:

Decide according to what you have

Determine the type of available OpenSSL extension:

  • OpenSSL on IBM Z and LinuxONE - out of the box

    Main purpose: Symmetric cryptography, digesting,and selected asymmetric cryptography

    Most cryptographic applications are built with compiled-in OpenSSL support and can thus exploit the built-in IBM Z cryptographic hardware support transparently without the need of further OpenSSL configurations.

    Symmetric ciphers and hash algorithms (digests) are already implicitly accelerated by OpenSSL itself using CPACF. Therefore, those functions will probably be processed slower when routed to IBMCA.

    Also, for IBM z15 or LinuxONE II and later, elliptic curve cryptography (ECC) with curves P-256, P-384, P-521, Ed25519, X25519, Ed448, or X448 is implicitly accelerated with OpenSSL by the use of CPACF.

    Thus, users can exploit the combination of OpenSSL and IBM Zand LinuxONE cryptographic hardware without any complexity for the most important cryptographic operations. You can achieve this out of the box, just by running applications that link or use OpenSSL. This is because OpenSSL on IBM Z and LinuxONE implicitly uses IBM Z hardware acceleration, mostly on CPACF. An overview of implicitly provided acceleration is in:

    Maybe this is all you need to know for your purposes. You want to learn about CPACF? Then you can additionally read:

  • OpenSSL on IBM Z and LinuxONE - configured with IBMCA

    Main purpose: Asymmetric cryptography: RSA, ECC, DH, DSA

    A prerequisite for performing asymmetric cryptography with IBMCA is to have access to cryptographic adapters in accelerator mode or CCA coprocessor mode. For OpenSSL version 3.0 or later, use the IBMCA provider, for OpenSSL version 1.1.1, use the IBMCA engine.

    Important: The use of engines in general, and specifically the IBMCA engine, is strongly discouraged starting with OpenSSL versions 3.0. Use the IBMCA provider instead.

    After checking the prerequisites, you must check which of the IBMCA flavors are contained in the package of your distribution. For OpenSSL 1.1.1, only the IBMCA engine can be available. Starting with OpenSSL 3.0, either flavor, or both, IBMCA engine and IBMCA provider can be available. Then read the adequate information:

    If you are interested into a deep dive into the topic of engines and providers for OpenSSL, you may find useful information in:

    With IBMCA, acceleration for clear key processing may be provided on IBM Z cryptographic adapters. Therefore, you may also want to read:

  • OpenSSL on IBM Z and LinuxONE - configured for exploiting PKCS#11:

    Another example for an extension of OpenSSL is the exploitation of PKCS#11 using the libp11 engine. This engine is useful in scenarios where you want to use OpenSSL together with keys protected by a hardware security module (HSM), also called secure keys. Such a scenario is presented in:

    If you are curious about secure keys, and how these are processed, you may also read:

  • Further information you may find useful when working with OpenSSL on IBM Z cryptographic hardware is in the following topics: