9.10. Configuring unlocking of LUKS-encrypted volumes by using a PKCS #11 pin

Procedure

1. Identify the LUKS-encrypted volume for PBD. In the following example, the block device is referred as /dev/sda2:

   # lsblk
   NAME                                          MAJ:MIN RM   SIZE RO TYPE  MOUNTPOINT
   sda                                             8:0    0    12G  0 disk
   ├─sda1                                          8:1    0     1G  0 part  /boot
   └─sda2                                          8:2    0    11G  0 part
     └─luks-40e20552-2ade-4954-9d56-565aa7994fb6 253:0    0    11G  0 crypt
       ├─rhel-root                               253:0    0   9.8G  0 lvm   /
       └─rhel-swap                               253:1    0   1.2G  0 lvm   [SWAP]

2. Identify the URI of the PKCS #11 device you want to use for unlocking volumes, for example:

   $ pkcs11-tool -L | grep uri
   uri            	: pkcs11:model=PKCS%2315%20emulated;manufacturer=piv_II;serial=42facd1f749ece7f;token=clevis
   uri            	: pkcs11:model=PKCS%2315%20emulated;manufacturer=OpenPGP%20project;serial=000f06080f4f;token=OpenPGP%20card%20%28User%20PIN%29

3. Bind the volume to a PKCS #11 device with the clevis luks bind command, for example:

   # clevis luks bind -d /dev/sda2 pkcs11 '{"uri":"pkcs11:model=PKCS%2315%20emulated;manufacturer=OpenPGP%20project;serial=000f06080f4f;token=OpenPGP%20card%20%28User%20PIN%29;id=%03;object=Authentication%20key;type=public"}'
   …
   Do you wish to initialize /dev/sda2? [yn] y
   Enter existing LUKS password:

   This command performs the following steps:

   1. Creates a new key with the same entropy as the LUKS master key.
   2. Encrypts the new key with Clevis.
   3. Stores the Clevis JWE object in the LUKS2 header token or uses LUKSMeta if the non-default LUKS1 header is used.
   4. Enables the new key for use with LUKS.

4. Optionally: If your scenario requires specifying the module to use, add the module-path URI parameter:

   # clevis luks bind -d /dev/sda2 pkcs11 '{"uri":"pkcs11:module-path=/usr/lib64/libykcs11.so.2";model=PKCS%2315%20emulated;manufacturer=OpenPGP%20project;serial=000f06080f4f;token=OpenPGP%20card%20%28User%20PIN%29;id=%03;object=Authentication%20key;type=public}'

5. Enable the clevis-luks-pkcs11-askpass.socket unit:

   # systemctl enable --now clevis-luks-pkcs11-askpass.socket

6. Open the /etc/crypttab file in a text editor and identify the line containing the LUKS-encrypted volume you want to unlock by the PKCS #11 pin, for example:

   luks-6e38d5e1-7f83-43cc-819a-7416bcbf9f84 UUID=6e38d5e1-7f83-43cc-819a-7416bcbf9f84 - -

7. Replace the dashes with the /run/systemd/clevis-pkcs11.sock file path and the keyfile-timeout option:

   luks-6e38d5e1-7f83-43cc-819a-7416bcbf9f84 UUID=6e38d5e1-7f83-43cc-819a-7416bcbf9f84 /run/systemd/clevis-pkcs11.sock keyfile-timeout=30s

   The keyfile-timeout option provides a fall-through mechanism for when an unlocking error occurs and the system requires entering the passphrase manually through the console.

8. Save the changes and exit the editor.

9. To enable the early boot system to process the disk binding, which is required for unlocking root file systems, use the dracut tool on an already installed system:

   # dracut -fv --regenerate-all

10. Restart the system.

    During the following boot process, the system prompts for the PKCS #11 device PIN and decrypts the corresponding configured encrypted disk only in case you enter the correct PIN.

Verification

1. Instead of manually testing the boot process, you can encrypt and decrypt a text message with the following command:

   # echo "top secret" | clevis encrypt pkcs11 '{"uri":"pkcs11:module-path=/usr/lib64/libykcs11.so.2?pin-value=<PIN>"}' | clevis decrypt

   Replace <PIN> with a PIN value. You must enter this PIN value to decrypt the message.

2. Verify that the Clevis JWE object is successfully placed in a LUKS header, for example:

   # clevis luks list -d /dev/sda2
   1: pkcs11 '{"uri": "pkcs11:model=PKCS%2315%20emulated;manufacturer=piv_II;
   serial=0a35ba26b062b9c5;token=clevis;id=%02;object=Encryption%20Key?
   module-path=/usr/lib64/libykcs11.so.2"}'