bootc feat: Add LUKS encryption using IBM Crypto Express Card

Hi, We would like to enable IBM Crypto Express card (CEX) luks encryption in bootc. The cex based luks encryption feature has been enabled from 4.19. We added this feature in the Ignition which takes care of the luks encryption.

Here are the few highlight and working part specific to CEX based luks encryption.

1.  A key slot in luks2 header stores a wrapped copy of the volume key,where the wrapping  key is derived from the users passphrase or "keyfile".
2.  In the infrastructure for protected volume encryption, the luks2 volume key is secure key.
3.  The effective volume is twofold protected: it is encrypted by an AES master key
    from a CCA or EP11 coProcessor and by a wrapping key or KEK derived from a passphrase or "keyfile".
4.  Therefore to unlock a luks2 volume a passphrase - provided interactively or from this "keyfile"
    is required to decrypt the outer wrapping.
5.  The security provided by the passphrase or "keyfile" is typically much lower than that provided by the wrapping AES master key.
6.  Therefore the password or "keyfile" may be exposed without any loss of security.
7.  When a secure key for the PAES cipher is provide to dm-crypt inorder to open a volume,
    it automatically transforms this secure key into a protected key that can be interpreted by the CPACF.
8. The actual effective key of the luks2 volume key is never exposed to the operating system.

The following figure show how the Secure keys get generated.

1. A secure key is created by using a zkey command. The zkey utility generates the secure key with the help of the pkey utility and an assigned Crypto Express adapter (with master key). The secure key is also stored in the key repository.
2. The use of the zkey cryptsetup command generates output strings that are copied and pasted to the cryptsetup command to create the encrypted volume with the appropriate secure key.
3. The cryptsetup utility formats the physical volume and writes the encrypted secure key and cipher information to the LUKS2 header of the volume.

To Open the Luks Device

1. The cryptsetup utility fetches the secure key from the LUKS2 header.
2. The cryptsetup utility passes the secure key to dm-crypt.
3. The dm-crypt passes the secure key to paes for conversion into a protected key by using pkey.
4. The pkey module starts the process for converting the secure key to a protected key.
5. The secure key is unwrapped by the CCA coprocessor in the Crypto Express adapter by
using the master key.
6. The unwrapped secure key (effective key) is rewrapped by using a transport key that is specific to the assigned domain ID.
7. By using firmware, CPACF creates a protected key and sends it to the pkey module for volume read/write usage with paes and dm-crypt.

Aug 25 '25 02:08 madhu-pillai

We would like to enable IBM Crypto Express card (CEX) luks encryption in bootc.

Conceptually, bootc is independent of block storage. It operates entirely on the filesystem level and is agnostic to how that filesystem operates.

There is an install to-disk method that does support LUKS via systemd-cryptenroll, but I consider this somewhat of a mistake (vs deferring to external installers and/or handling via repart). But anyways, is this what you were thinking of adjusting? (It raises the question of course of whether systemd-cryptenroll (and cryptsetup) could learn to have this zkey as a backend)

We added this feature in the Ignition which takes care of the luks encryption.

Right that makes total sense. If this is for CoreOS then as far as I am aware there is zero changes needed to bootc.

Aug 26 '25 14:08 cgwalters

Thank you Colin for the support here.

There is an install to-disk method that does support LUKS via systemd-cryptenroll, but I consider this somewhat of a mistake (vs deferring to external installers and/or handling via repart). But anyways, is this what you were thinking of adjusting?

Yes.

(It raises the question of course of whether systemd-cryptenroll (and cryptsetup) could learn to have this zkey as a backend)

There are few dependency two kernel module and zkey, zkey-cryptsetup, lszcrypt requires rpm s390utils-base-2.34.0-1.fc41.s390x. This rpm is included in the RHCOS, But due to the perl dependency and lot heavier we exclude in the FCOS.

Eg: To encrypt a volume .

List the Crypto Card

# lszcrypt -V
CARD.DOM TYPE  MODE        STATUS     REQUESTS  PENDING HWTYPE QDEPTH FUNCTIONS  DRIVER     
--------------------------------------------------------------------------------------------
00       CEX8C CCA-Coproc  online          372        0     14     08 S--D--N-F- cex4card   
00.0035  CEX8C CCA-Coproc  in use            -        -     14     08 S--D--N-F- vfio_ap    
00.0036  CEX8C CCA-Coproc  in use            -        -     14     08 S--D--N-F- vfio_ap    
00.0037  CEX8C CCA-Coproc  in use            -        -     14     08 S--D--N-F- vfio_ap    
00.0038  CEX8C CCA-Coproc  in use            -        -     14     08 S--D--N-F- vfio_ap    
00.0039  CEX8C CCA-Coproc  in use            -        -     14     08 S--D--N-F- vfio_ap

Steps Load kernel module specific to crypto - In the ignition we add this in module-setup.sh in dracut.

         instmods -c zcrypt_cex4
         instmods -c pkey_cca

Generate the SecureKeys using the specific domain (We can use all the cards) Here 00 is the card and 0035 is domain to generate the secure keys. The generated key get placed under /etc/zkey/repository/secure_xtskey1.skey

# zkey generate --name secure_xtskey1 --keybits 256 --xts --key-type CCA-AESCIPHER --volumes /dev/disk/by-path/ccw-0.0.ff01-part1:enc-disk1 --volume-type LUKS2 --apqns 00.0035

Format the Disk`

# cryptsetup luksFormat --type luks2 --master-key-file '/etc/zkey/repository/secure_xtskey1.skey' --key-size 2176 --cipher paes-xts-plain64 --sector-size 4096 /dev/disk/by-path/ccw-0.0.ff01-part1

Run Verification pattern - the zkey-cryptsetup setvp command to set the verification pattern into the LUKS2 header. The verification pattern is used to identify the valid effective key during recovery actions.

# zkey-cryptsetup setvp /dev/mapper/enc-disk1

There is shorter method to run the cryptsetup command. zkey cryptsetup --volumes /dev/mapper/enc-disk1 --run the cryptsetup command the verification pattern on single shot. This command pull the details from the key we generated on the first step.

Key                          : securekey.skey                                        
-------------------------------------------------------------------------------------
        Description          : 
        Secure key size      : 272 bytes
        Clear key size       : 512 bits
        XTS type key         : Yes
        Key type             : CCA-AESCIPHER
        Volumes              : /dev/mapper/disk1:enc-disk1
        APQNs                : 00.0038
        Key file name        : /etc/zkey/repository/securekey.skey.skey
        Sector size          : (system default)
        Volume type          : LUKS2
        Verification pattern : 599c2fc23c4072bc0a824e0afe2643d6
                               fb9751266250712192ba1e4eada005dc
        KMS                  : (local)
        KMS key label        : (local)
        Dummy passphrase     : (none)
        Created              : 2025-08-30 03:10:27
        Changed              : (never)
        Re-enciphered        : (never)

Aug 30 '25 03:08 madhu-pillai

For production use in Fedora derivatives (including especially RHEL) we've been pointing people towards Anaconda more. I think that would make the most sense as a first target for this, especially as a backend for https://pykickstart.readthedocs.io/en/latest/kickstart-docs.html#autopart

Aug 30 '25 15:08 cgwalters