The EP11 crypto stack

The EP11 crypto stack for Linux on Z consists of various components within the different layers: An application sends a request down to the hardware (cryptographic adapter), via the device driver and the firmware. The request is routed all the layers down and back again, and the request result is returned to the application. The stack thus provides an end-to-end solution for cryptographic operations.

For example, an application sends an encryption request to the crypto adapter. Through various interfaces, such a request is propagated from the application layer down to the target crypto adapter hardware. On its way down, the request passes through the involved layers: the standard crypto interfaces, the IBM Z® crypto libraries, and the operating system kernel. The zcrypt device driver finally sends the request to the Crypto Express EP11 coprocessor. The resulting request output is sent back to the application just the other way round through the layer interfaces.

Figure 1 illustrates the EP11 crypto stack within the Linux on Z environment. The components that make up the Linux on Z EP11 enablement are highlighted:

• the EP11 token within openCryptoki
• the host part of the EP11 library (located in user space, which is named libep11.so). In version 2.0, libep11.so is a symbolic link to the versioned library libep11.so.2 and this in turn is a symbolic link to libep11.so.2.0.0.
• the EP11 extension of the zcrypt device driver. This extension was included with kernel level 3.14 on https://www.kernel.org/. Note that distributions sometimes back-port features from newer kernel.org kernels into their current kernel versions. Therefore check with your distribution partner, whether your distribution release supports the EP11 enablement, if its kernel version is older than 3.14.
• the module part of the EP11 library, that is, the EP11 firmware that is installed on the Crypto Express EP11 coprocessor adapter hardware.

openCryptoki can be used directly through the openCryptoki shared library (C API).

openCryptoki supports several token types, which can offer different functionality for different hardware devices or software solutions. Tokens of type EP11 (aka EP11 tokens) interact with the host part of the EP11 library. EP11 can operate with the Crypto Express adapter (CEX*P) with EP11 firmware load for processing cryptographic functions.

The EP11 token itself does not implement PKCS #11 but provides services for accessing EP11 functions to openCryptoki. For a description of these services or the interface between the common part of openCryptoki and its tokens, see the openCryptoki documentation. Once the EP11 token is configured, cryptographic functions from the EP11 token are available to an application through the PKCS #11 API provided by the common openCryptoki code. The EP11 token itself accesses the EP11 library. The EP11 library is divided into the host part and the module part, which runs in the Crypto Express EP11 coprocessor. An installed EP11 library is a prerequisite for enabling openCryptoki to use the EP11 token. The EP11 library passes requests to the CEX*P EP11 coprocessor through the zcrypt device driver of Linux on Z.

The host part of the EP11 library creates cryptographic requests from the EP11 token in Abstract Syntax Notation One (ASN.1). These requests are sent to and understood by the CEX*P adapter. The host part also converts response buffers that are received from the adapter into data structures that are expected by the EP11 token. The EP11 token makes these APIs accessible to openCryptoki and thus the applications, but does not implement any cryptographic mechanism. The mechanisms available and their parameters depend on the EP11 implementation (EP11 library and CEX*P card) and its configuration. The PKCS #11 Cryptographic Token Interface Standard defines methods for inquiring available mechanisms. You can obtain an inquiry of all available mechanisms and their parameters using the PKCS #11 functions C_GetMechanismList and C_GetMechanismInfo.

Besides the CEX*P adapter that is loaded with the EP11 firmware (EP11 module part), the EP11 token furthermore requires a zcrypt device driver within the kernel, extended with the Linux on Z EP11 enablement support (see Installing and loading the cryptographic device driver). In addition, the EP11 token requires the availability of the host part of the EP11 library.