Chapter 11. Configuring automated unlocking of encrypted volumes by using policy-based decryption

Procedure

1. To install Clevis and its pins on a system with an encrypted volume:

   # yum install clevis

2. To decrypt data, use a clevis decrypt command and provide a cipher text in the JSON Web Encryption (JWE) format, for example:

   $ clevis decrypt < secret.jwe

Procedure

1. To install the tang package and its dependencies, enter the following command as root:

   # yum install tang

2. Pick an unoccupied port, for example, 7500/tcp, and allow the tangd service to bind to that port:

   # semanage port -a -t tangd_port_t -p tcp 7500

   Note that a port can be used only by one service at a time, and thus an attempt to use an already occupied port implies the ValueError: Port already defined error message.

3. Open the port in the firewall:

   # firewall-cmd --add-port=7500/tcp
   # firewall-cmd --runtime-to-permanent

4. Enable the tangd service:

   # systemctl enable tangd.socket

5. Create an override file:

   # systemctl edit tangd.socket

6. In the following editor screen, which opens an empty override.conf file located in the /etc/systemd/system/tangd.socket.d/ directory, change the default port for the Tang server from 80 to the previously picked number by adding the following lines:

   [Socket]
   ListenStream=
   ListenStream=7500

   Important

   Insert the previous code snippet between the lines starting with # Anything between here and # Lines below this, otherwise the system discards your changes.

7. Save the changes by pressing Ctrl+O and Enter. Exit the editor by pressing Ctrl+X.

8. Reload the changed configuration:

   # systemctl daemon-reload

9. Check that your configuration is working:

   # systemctl show tangd.socket -p Listen
   Listen=[::]:7500 (Stream)

10. Start the tangd service:

    # systemctl restart tangd.socket

    Because tangd uses the systemd socket activation mechanism, the server starts as soon as the first connection comes in. A new set of cryptographic keys is automatically generated at the first start. To perform cryptographic operations such as manual key generation, use the jose utility.

Procedure

1. Rename all keys in the /var/db/tang key database directory to have a leading . to hide them from advertisement. Note that the file names in the following example differs from unique file names in the key database directory of your Tang server:

   # cd /var/db/tang
   # ls -l
   -rw-r--r--. 1 root root 349 Feb  7 14:55 UV6dqXSwe1bRKG3KbJmdiR020hY.jwk
   -rw-r--r--. 1 root root 354 Feb  7 14:55 y9hxLTQSiSB5jSEGWnjhY8fDTJU.jwk
   # mv UV6dqXSwe1bRKG3KbJmdiR020hY.jwk .UV6dqXSwe1bRKG3KbJmdiR020hY.jwk
   # mv y9hxLTQSiSB5jSEGWnjhY8fDTJU.jwk .y9hxLTQSiSB5jSEGWnjhY8fDTJU.jwk

2. Check that you renamed and therefore hid all keys from the Tang server advertisement:

   # ls -l
   total 0

3. Generate new keys using the /usr/libexec/tangd-keygen command in /var/db/tang on the Tang server:

   # /usr/libexec/tangd-keygen /var/db/tang
   # ls /var/db/tang
   3ZWS6-cDrCG61UPJS2BMmPU4I54.jwk zyLuX6hijUy_PSeUEFDi7hi38.jwk

4. Check that your Tang server advertises the signing key from the new key pair, for example:

   # tang-show-keys 7500
   3ZWS6-cDrCG61UPJS2BMmPU4I54

5. On your NBDE clients, use the clevis luks report command to check if the keys advertised by the Tang server remains the same. You can identify slots with the relevant binding using the clevis luks list command, for example:

   # clevis luks list -d /dev/sda2
   1: tang '{"url":"http://tang.srv"}'
   # clevis luks report -d /dev/sda2 -s 1
   ...
   Report detected that some keys were rotated.
   Do you want to regenerate luks metadata with "clevis luks regen -d /dev/sda2 -s 1"? [ynYN]

6. To regenerate LUKS metadata for the new keys either press y to the prompt of the previous command, or use the clevis luks regen command:

   # clevis luks regen -d /dev/sda2 -s 1

7. When you are sure that all old clients use the new keys, you can remove the old keys from the Tang server, for example:

   # cd /var/db/tang
   # rm .*.jwk

Procedure

1. Open the RHEL web console by entering the following address in a web browser:

   https://<localhost>:9090

   Replace the <localhost> part by the remote server’s host name or IP address when you connect to a remote system.

2. Provide your credentials and click Storage. In the Filesystems section, click the disk that contains an encrypted volume you plan to add to unlock automatically.
3. In the following window listing partitions and drive details of the selected disk, click > next to the encrypted file system to expand details of the encrypted volume you want to unlock using the Tang server, and click Encryption.

4. Click + in the Keys section to add a Tang key:

   

5. Select Tang keyserver as Key source, provide the address of your Tang server, and a password that unlocks the LUKS-encrypted device. Click Add to confirm:

   

   The following dialog window provides a command to verify that the key hash matches.

6. In a terminal on the Tang server, use the tang-show-keys command to display the key hash for comparison. In this example, the Tang server is running on the port 7500:

   # tang-show-keys 7500
   fM-EwYeiTxS66X3s1UAywsGKGnxnpll8ig0KOQmr9CM

7. Click Trust key when the key hashes in the web console and in the output of previously listed commands are the same:

   
8. In RHEL 8.8 and later, after you select an encrypted root file system and a Tang server, you can skip adding the rd.neednet=1 parameter to the kernel command line, installing the clevis-dracut package, and regenerating an initial RAM disk (initrd). For non-root file systems, the web console now enables the remote-cryptsetup.target and clevis-luks-akspass.path systemd units, installs the clevis-systemd package, and adds the _netdev parameter to the fstab and crypttab configuration files.

Verification

1. Check that the newly added Tang key is now listed in the Keys section with the Keyserver type:

   

2. Verify that the bindings are available for the early boot, for example:

   # lsinitrd | grep clevis
   clevis
   clevis-pin-null
   clevis-pin-sss
   clevis-pin-tang
   clevis-pin-tpm2
   lrwxrwxrwx   1 root     root           48 Feb 14 17:45 etc/systemd/system/cryptsetup.target.wants/clevis-luks-askpass.path…
   …

Procedure

1. To automatically unlock an existing LUKS-encrypted volume, install the clevis-luks subpackage:

   # yum install clevis-luks

2. 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]

3. Bind the volume to a Tang server using the clevis luks bind command:

   # clevis luks bind -d /dev/sda2 tang '{"url":"http://tang.srv"}'
   The advertisement contains the following signing keys:
   
   _OsIk0T-E2l6qjfdDiwVmidoZjA
   
   Do you wish to trust these keys? [ynYN] y
   You are about to initialize a LUKS device for metadata storage.
   Attempting to initialize it may result in data loss if data was
   already written into the LUKS header gap in a different format.
   A backup is advised before initialization is performed.
   
   Do you wish to initialize /dev/sda2? [yn] y
   Enter existing LUKS password:

   This command performs four 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.
   Note

   The binding procedure assumes that there is at least one free LUKS password slot. The clevis luks bind command takes one of the slots.

   The volume can now be unlocked with your existing password as well as with the Clevis policy.

4. To enable the early boot system to process the disk binding, use the dracut tool on an already installed system:

   # yum install clevis-dracut

   In RHEL, Clevis produces a generic initrd (initial RAM disk) without host-specific configuration options and does not automatically add parameters such as rd.neednet=1 to the kernel command line. If your configuration relies on a Tang pin that requires network during early boot, use the --hostonly-cmdline argument and dracut adds rd.neednet=1 when it detects a Tang binding:

   # dracut -fv --regenerate-all --hostonly-cmdline

   Alternatively, create a .conf file in the /etc/dracut.conf.d/, and add the hostonly_cmdline=yes option to the file, for example:

   # echo "hostonly_cmdline=yes" > /etc/dracut.conf.d/clevis.conf

   Note

   You can also ensure that networking for a Tang pin is available during early boot by using the grubby tool on the system where Clevis is installed:

   # grubby --update-kernel=ALL --args="rd.neednet=1"

   Then you can use dracut without --hostonly-cmdline:

   # dracut -fv --regenerate-all

Verification

1. To verify that the Clevis JWE object is successfully placed in a LUKS header, use the clevis luks list command:

   # clevis luks list -d /dev/sda2
   1: tang '{"url":"http://tang.srv:port"}'

Procedure

1. To automatically unlock an existing LUKS-encrypted volume, install the clevis-luks subpackage:

   # yum install clevis-luks

2. 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]

3. Bind the volume to a TPM 2.0 device using the clevis luks bind command, for example:

   # clevis luks bind -d /dev/sda2 tpm2 '{"hash":"sha256","key":"rsa"}'
   ...
   Do you wish to initialize /dev/sda2? [yn] y
   Enter existing LUKS password:

   This command performs four 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.

      Note

      The binding procedure assumes that there is at least one free LUKS password slot. The clevis luks bind command takes one of the slots.

      Alternatively, if you want to seal data to specific Platform Configuration Registers (PCR) states, add the pcr_bank and pcr_ids values to the clevis luks bind command, for example:

      # clevis luks bind -d /dev/sda2 tpm2 '{"hash":"sha256","key":"rsa","pcr_bank":"sha256","pcr_ids":"0,1"}'

      Warning

      Because the data can only be unsealed if PCR hashes values match the policy used when sealing and the hashes can be rewritten, add a strong passphrase that enable you to unlock the encrypted volume manually when a value in a PCR changes.

      If the system cannot automatically unlock your encrypted volume after an upgrade of the shim-x64 package, follow the steps in the Clevis TPM2 no longer decrypts LUKS devices after a restart KCS article.

4. The volume can now be unlocked with your existing password as well as with the Clevis policy.

5. To enable the early boot system to process the disk binding, use the dracut tool on an already installed system:

   # yum install clevis-dracut
   # dracut -fv --regenerate-all

Verification

1. To verify that the Clevis JWE object is successfully placed in a LUKS header, use the clevis luks list command:

   # clevis luks list -d /dev/sda2
   1: tpm2 '{"hash":"sha256","key":"rsa"}'

Procedure

1. Check which LUKS version the volume, for example /dev/sda2, is encrypted by and identify a slot and a token that is bound to Clevis:

   # cryptsetup luksDump /dev/sda2
   LUKS header information
   Version:        2
   ...
   Keyslots:
     0: luks2
   ...
   1: luks2
         Key:        512 bits
         Priority:   normal
         Cipher:     aes-xts-plain64
   ...
         Tokens:
           0: clevis
                 Keyslot:  1
   ...

   In the previous example, the Clevis token is identified by 0 and the associated key slot is 1.

2. In case of LUKS2 encryption, remove the token:

   # cryptsetup token remove --token-id 0 /dev/sda2

3. If your device is encrypted by LUKS1, which is indicated by the Version: 1 string in the output of the cryptsetup luksDump command, perform this additional step with the luksmeta wipe command:

   # luksmeta wipe -d /dev/sda2 -s 1

4. Wipe the key slot containing the Clevis passphrase:

   # cryptsetup luksKillSlot /dev/sda2 1

Procedure

1. Instruct Kickstart to partition the disk such that LUKS encryption has enabled for all mount points, other than /boot, with a temporary password. The password is temporary for this step of the enrollment process.

   part /boot --fstype="xfs" --ondisk=vda --size=256
   part / --fstype="xfs" --ondisk=vda --grow --encrypted --passphrase=temppass

   Note that OSPP-compliant systems require a more complex configuration, for example:

   part /boot --fstype="xfs" --ondisk=vda --size=256
   part / --fstype="xfs" --ondisk=vda --size=2048 --encrypted --passphrase=temppass
   part /var --fstype="xfs" --ondisk=vda --size=1024 --encrypted --passphrase=temppass
   part /tmp --fstype="xfs" --ondisk=vda --size=1024 --encrypted --passphrase=temppass
   part /home --fstype="xfs" --ondisk=vda --size=2048 --grow --encrypted --passphrase=temppass
   part /var/log --fstype="xfs" --ondisk=vda --size=1024 --encrypted --passphrase=temppass
   part /var/log/audit --fstype="xfs" --ondisk=vda --size=1024 --encrypted --passphrase=temppass

2. Install the related Clevis packages by listing them in the %packages section:

   %packages
   clevis-dracut
   clevis-luks
   clevis-systemd
   %end

3. Optionally, to ensure that you can unlock the encrypted volume manually when required, add a strong passphrase before you remove the temporary passphrase. See the How to add a passphrase, key, or keyfile to an existing LUKS device article for more information.

4. Call clevis luks bind to perform binding in the %post section. Afterward, remove the temporary password:

   %post
   clevis luks bind -y -k - -d /dev/vda2 \
   tang '{"url":"http://tang.srv"}' <<< "temppass"
   cryptsetup luksRemoveKey /dev/vda2 <<< "temppass"
   dracut -fv --regenerate-all
   %end

   If your configuration relies on a Tang pin that requires network during early boot or you use NBDE clients with static IP configurations, you have to modify the dracut command as described in Configuring manual enrollment of LUKS-encrypted volumes.

   Note that the -y option for the clevis luks bind command is available from RHEL 8.3. In RHEL 8.2 and older, replace -y by -f in the clevis luks bind command and download the advertisement from the Tang server:

   %post
   curl -sfg http://tang.srv/adv -o adv.jws
   clevis luks bind -f -k - -d /dev/vda2 \
   tang '{"url":"http://tang.srv","adv":"adv.jws"}' <<< "temppass"
   cryptsetup luksRemoveKey /dev/vda2 <<< "temppass"
   dracut -fv --regenerate-all
   %end

   Warning

   The cryptsetup luksRemoveKey command prevents any further administration of a LUKS2 device on which you apply it. You can recover a removed master key using the dmsetup command only for LUKS1 devices.

Procedure

1. To automatically unlock a LUKS-encrypted removable storage device, such as a USB drive, install the clevis-udisks2 package:

   # yum install clevis-udisks2

2. Reboot the system, and then perform the binding step using the clevis luks bind command as described in Configuring manual enrollment of LUKS-encrypted volumes, for example:

   # clevis luks bind -d /dev/sdb1 tang '{"url":"http://tang.srv"}'

3. The LUKS-encrypted removable device can be now unlocked automatically in your GNOME desktop session. The device bound to a Clevis policy can be also unlocked by the clevis luks unlock command:

   # clevis luks unlock -d /dev/sdb1

Procedure

1. Pull the tang container image from the registry.redhat.io registry:

   # podman pull registry.redhat.io/rhel8/tang

2. Run the container, specify its port, and specify the path to the Tang keys. The previous example runs the tang container, specifies the port 7500, and indicates a path to the Tang keys of the /var/db/tang directory:

   # podman run -d -p 7500:7500 -v tang-keys:/var/db/tang --name tang registry.redhat.io/rhel8/tang

   Note that Tang uses port 80 by default but this may collide with other services such as the Apache HTTP server.

3. [Optional] For increased security, rotate the Tang keys periodically. You can use the tangd-rotate-keys script, for example:

   # podman run --rm -v tang-keys:/var/db/tang registry.redhat.io/rhel8/tang tangd-rotate-keys -v -d /var/db/tang
   Rotated key 'rZAMKAseaXBe0rcKXL1hCCIq-DY.jwk' -> .'rZAMKAseaXBe0rcKXL1hCCIq-DY.jwk'
   Rotated key 'x1AIpc6WmnCU-CabD8_4q18vDuw.jwk' -> .'x1AIpc6WmnCU-CabD8_4q18vDuw.jwk'
   Created new key GrMMX_WfdqomIU_4RyjpcdlXb0E.jwk
   Created new key _dTTfn17sZZqVAp80u3ygFDHtjk.jwk
   Keys rotated successfully.

Procedure

1. Create a playbook file, for example ~/playbook.yml, with the following content:

   ---
   - hosts: managed-node-01.example.com
     roles:
       - rhel-system-roles.nbde_server
     vars:
       nbde_server_rotate_keys: yes
       nbde_server_manage_firewall: true
       nbde_server_manage_selinux: true

   This example playbook ensures deploying of your Tang server and a key rotation.

   When nbde_server_manage_firewall and nbde_server_manage_selinux are both set to true, the nbde_server role uses the firewall and selinux roles to manage the ports used by the nbde_server role.

2. Validate the playbook syntax:

   $ ansible-playbook --syntax-check ~/playbook.yml

   Note that this command only validates the syntax and does not protect against a wrong but valid configuration.

3. Run the playbook:

   $ ansible-playbook ~/playbook.yml

Procedure

1. Create a playbook file, for example ~/playbook.yml, with the following content:

   - hosts: managed-node-01.example.com
     roles:
       - rhel-system-roles.nbde_client
     vars:
       nbde_client_bindings:
         - device: /dev/rhel/root
           encryption_key_src: /etc/luks/keyfile
           servers:
             - http://server1.example.com
             - http://server2.example.com
         - device: /dev/rhel/swap
           encryption_key_src: /etc/luks/keyfile
           servers:
             - http://server1.example.com
             - http://server2.example.com

   This example playbook configures Clevis clients for automated unlocking of two LUKS-encrypted volumes when at least one of two Tang servers is available

   The nbde_client System Role supports only scenarios with Dynamic Host Configuration Protocol (DHCP). To use NBDE for clients with static IP configuration use the following playbook:

   - hosts: managed-node-01.example.com
     roles:
       - rhel-system-roles.nbde_client
     vars:
       nbde_client_bindings:
         - device: /dev/rhel/root
           encryption_key_src: /etc/luks/keyfile
           servers:
             - http://server1.example.com
             - http://server2.example.com
         - device: /dev/rhel/swap
           encryption_key_src: /etc/luks/keyfile
           servers:
             - http://server1.example.com
             - http://server2.example.com
     tasks:
       - name: Configure a client with a static IP address during early boot
         ansible.builtin.command:
           cmd: grubby --update-kernel=ALL --args='GRUB_CMDLINE_LINUX_DEFAULT="ip={{ <ansible_default_ipv4.address> }}::{{ <ansible_default_ipv4.gateway> }}:{{ <ansible_default_ipv4.netmask> }}::{{ <ansible_default_ipv4.alias> }}:none"'

   In this playbook, replace the <ansible_default_ipv4.*> strings with IP addresses of your network, for example: ip={{ 192.0.2.10 }}::{{ 192.0.2.1 }}:{{ 255.255.255.0 }}::{{ ens3 }}:none.

2. Validate the playbook syntax:

   $ ansible-playbook --syntax-check ~/playbook.yml

   Note that this command only validates the syntax and does not protect against a wrong but valid configuration.

3. Run the playbook:

   $ ansible-playbook ~/playbook.yml