LUKS encryption using CEX in an IBM Z or IBM LinuxONE environment 

                                                                                                           Preface 

Enabling hardware-based Linux Unified Key Setup (LUKS) encryption via IBM Crypto Express (CEX) in an IBM Z or IBM LinuxONE environment for Red Hat OpenShift cluster setups. 

LUKS is a standardized way to encrypt block devices on Linux systems. The CEX based LUKS encryption is similar to the existing LUKS encryption offered by x86 architecture using a TPM device or Network Bound Disk Encryption (NBDE) using Clevis utility in Ignition. The difference is CEX enabled LUKS encryption does not require Clevis utility. The Clevis utility only manages the passphrase that is used to encrypt/decrypt a LUKS device either through TPM device or NBDE.  

CEX based LUKS encryption uses a Protected key. Protected Key is a data-encrypting key that itself is encrypted by a CPACF (Central Processor Assist for Cryptographic Function) wrapping key. The CPACF is a set of z/Architecture instructions provided by the Message Security Assist (MSA) facility and its extensions. It mainly provides symmetric ciphers and hash functions but also selected asymmetric functions (ECC) using clear keys and protected keys. The resulting encrypted key cannot be shared with another LPAR because the wrapping key is unique. In the case of Linux in a native LPAR, the wrapping key is specific to the LPAR. However, for guests of z/VM or KVM, the wrapping key is specific to the guest.  

The IBM Z platform offers cryptographic engines that provide high-speed cryptographic operations. CEX (Crypto Express Adapter) are required to generate the secure keys that are stored in the key repository. They are also required to generate protected keys from secure keys for Linux on Z data at-rest encryption. 

Crypto Express adapters are tamper-responding hardware security modules (HSM), which provide high security, high throughput cryptographic functions. The Crypto Express adapter adds a layer of protection for the storage.  

Refer the following diagram. 

This article explains how to configure LUKS-encrypted root volume for Red Hat OpenShift clusters deployed on z/VM and KVM, with support for both FCP and DASD devices. 

Note: 

Prerequisites: 

CCA Adapter must be >= CEX6C 

The latest Butane utility must be installed on the Linux instance that has administrative access to the OCP cluster. 

The OpenShift version must be >= 4.19 

Make sure that all the cluster nodes have at least one CEX card configured. For redundancy multiple cex cards can be configured.  

z/VM-based Installation.    

In the z/VM based installation assign the crypto adapter to appropriate VM before the installation. The following screenshot explains the cards assigned to VMs. 

The assignments can be queried with the command: Refer IBM zVM-command 

#cp q crypto ap 

KVM-based Installation. 

For configuring the crypto card in KVM on IBM Z or IBM LinuxONE, the following way we can create the vfio_ap pass through device. 

The following video illustrates the steps you must perform on the KVM host and in a virtual server  

 
https://video.ibm.com/recorded/133759252 

Follow the IBM documentation VFIO_AP 

The example script configures the mediated device for the CEX adapter which does not create a persistent mediated device and assumes the adapter is 0x00. 

Update the domain appropriate from the output of lszcrypt –V. If you need additional adapters, add the uuid:domain in the data field, as comma-separated values. Eg data="68cd2d83-3eef-4e45-b22c-534f90b16cb9:0x0035" 

#!/bin/bash 

echo "Setting vfio_ap and reseting the adapter"  

modprobe vfio_ap 

echo 0x0 > /sys/bus/ap/apmask  

echo 0x0 > /sys/bus/ap/aqmask 

echo "Started configure the adapter" 

#UUID can be generated from uuidgen command domain can be obtained from lszcrypt -V command. 

#Generate the UUID corresponding to the available CEX domain. 

data="68cd2d83-3eef-4e45-b22c-534f90b16cb9:0x0035,ba3f873c-3022-4534-9072-eb0d4530b137:0x0036,610e4724-c8c1-45ed-a498-ccfdadc1f2ca:0x0037,5c84eefb-cb45-4519-86d3-ba23e65e8896:0x0038,60cf6ec4-2741-44e2-84d2-0746f133db16:0x0039"  

Day - 1  

To enable LUKS in OpenShift, an additional manifest must be created and included as part of the installation process. 

In OpenShift Container Platform, RHCOS images are initially configured using a feature called Ignition, which runs only during the system’s first boot. After this initial boot, RHCOS nodes are managed by the Machine Config Operator (MCO) within the OpenShift cluster. 

Ignition is the utility responsible for manipulating disks during initial setup. It performs common disk-related tasks such as partitioning, formatting, writing files, and configuring users. On first boot, Ignition reads its configuration from the installation media or another specified location and applies it to the machine. 

The following procedure describes how to create a Machine Config for preparing LUKS encryption using the Butane utility. 

The Machine Config files generated by Butane must be placed in the OCP installation directory. 

DASD device butane config. 

Following the butane sugar for dasd device 99-master-machineconfig.bu 

variant: openshift 

version: 4.19.0 

metadata: 

  name: master-luks-storage (1) 

  labels: 

    machineconfiguration.openshift.io/role: master  

openshift: 

  fips: true (2) 

  kernel_arguments: 

    - rd.luks.key=/etc/luks/cex.key (3) 

boot_device: 

  layout: s390x-eckd (4) 

  luks: 

    device: /dev/dasda (5) 

    cex: 

      enabled: true (6) 

Convert the above butane config to an ignition- compatible file. 

[root@linux ~]# butane --strict 99-master-machineconfig.bu -o 99-master-luks-machineconfig.yaml  

The following shows the converted butane config to ignition. 

[root@linux ~]# cat 99-master-luks-machineconfig.yaml 

# Generated by Butane; do not edit 

apiVersion: machineconfiguration.openshift.io/v1 

kind: MachineConfig 

metadata: 

  labels: 

    machineconfiguration.openshift.io/role: master 

  name: master-luks-storage 

spec: 

  config: 

    ignition: 

      version: 3.5.0