Prerequisites

Hardware prerequisites

• An IBM z14™, z13®, z13s®, or any IBM LinuxONE™ machine with the CPACF feature installed. CPACF requires specific microcode to be loaded which you can order as no-charge feature code (LIC #3863).
• For redundancy, two or more IBM® Crypto Express5S or Crypto Express6S cryptographic coprocessors configured in CCA coprocessor mode or two or more Crypto Express7S coprocessors configured in EP11 mode.
• A Trusted Key Entry (TKE) workstation. For CCA coprocessors you need to install the CSUTKEcat TKE daemon from the CCA library to handle administrative commands between the TKE and the cryptographic coprocessors. For non-production CCA environments you can use the utilities from the CCA package instead of the TKE to perform operations on cryptographic coprocessors.
• For EP11 coprocessors, you need to install the EP11 TKE daemon (ep11TKEd) from the EP11 host library version 3.0.0 or later, which is listening on port 50004 for administrative TKE commands.
  Download the required libraries from:

  http://www.ibm.com/security/cryptocards

• Volumes to be encrypted (for example, SCSI or DASD volumes). For DASD volumes, you can only encrypt partitions, not the complete DASD.

  Generally speaking, any block device can be encrypted using the infrastructure for protected volume encryption.

Software prerequisites

• Any Linux™ distribution that includes the pkey and paes_s390 kernel modules and a dm-crypt version that supports LUKS2. Linux kernel upstream version 4.12 or later includes the required support for secure keys of type CCA-AESDATA. There might be distributions that have older kernel versions where the required modules have been back-ported.

  Support of secure keys of type CCA-AESCIPHER requires Linux kernel upstream version 5.4 (or older versions where the required modules have been back-ported).

  Support of secure keys of type EP11-AES requires Linux kernel upstream version 5.6 (or older versions where the required modules have been back-ported).

  The pkey kernel module requires permission for the AES key import functions. To grant this permission, go to the security settings of the applicable LPAR on the Hardware Management Console (HMC). In the CPACF Key Management Operations section, select the Permit AES Key import functions option. For z/VM® guests, the LPAR in which the hypervisor runs requires this option.

  Note: This action is only required for distributions that contain Linux kernels prior to upstream version 4.20. Also, the appropriate updates have been back-ported to several distributions, so that you do no longer need to manually apply the described permission for these distributions.

  However, for encrypting swap disks as described in Encrypting swap disks with protected keys, setting this permission manually is required anyway.

• The cryptsetup utility version 2.0.3 or later is required to configure an encrypted volume.
• The zkey utility from the s390-tools package (upstream version 2.6.0 or later). Use this utility to generate and manage secure keys.

  Support of secure keys of type CCA-AESCIPHER requires s390-tools package upstream version 2.12.

  Support of secure keys of type EP11-AES requires s390-tools package upstream version 2.13.

  Note: s390-tools versions might differ among various distributions, because the zkey utility might have been back-ported to earlier versions.
• The zkey-cryptsetup utility from the s390-tools package (upstream version 2.6.0 or later, also see previous note). Use this utility to support an AES master key change in order to avoid loss of data on volumes encrypted using the PAES cipher.
• The CCA 6.0 package or later from the software-package selection page is required to support secure keys of type CCA-AESCIPHER and CCA-AESDATA. It is also required to connect the TKE workstation to cryptographic coprocessors configured in CCA mode.

  For the support of secure keys of type EP11-AES, an IBM 4769 Crypto Express7 adapter configured in EP11 mode is required (CEX7P) and the EP11 host library version 3.0.0 or later must be installed. This library is also required for using the TKE to manage cryptographic coprocessors configured in EP11 mode.

Assumptions

In this documentation, it is assumed that the following setup has been installed:

• A Linux instance is installed as a z/VM or KVM guest virtual machine or in LPAR mode. Linux as a KVM guest can access cryptographic coprocessors starting with the following distributions:
  • Red Hat Enterprise Linux 8.0
  • SUSE Linux Enterprise Server 15 SP1
  • Ubuntu 18.04 LTS
• Two cryptographic coprocessor domains are configured to the LPAR or as dedicated adapters to the z/VM or KVM guest virtual machine.
  • The two domains have the same domain ID and are located on two distinct cryptographic coprocessors.
  • The same AES master key is set on the domains of both cryptographic coprocessors. Refer to How to set an AES master key for information about setting a CCA master key. For setting an EP11 master key, refer to Exploiting Enterprise PKCS #11 using openCryptoki.

    For comprehensive information about the TKE refer to:

    z/OS Cryptographic Services ICSF Trusted Key Entry Workstation User’s Guide, 
    shown in the list of z/OS Cryptograohic Services

• The volumes to be encrypted are configured to be persistently available to the Linux instance.