Chapter 18. Scanning the system for security compliance and vulnerabilities

Procedure

1. Download the latest RHSA OVAL definitions for your system:

   # wget -O - https://www.redhat.com/security/data/oval/v2/RHEL8/rhel-8.oval.xml.bz2 | bzip2 --decompress > rhel-8.oval.xml

2. Scan the system for vulnerabilities and save results to the vulnerability.html file:

   # oscap oval eval --report vulnerability.html rhel-8.oval.xml

Procedure

1. Download the latest RHSA OVAL definitions for your system:

   # wget -O - https://www.redhat.com/security/data/oval/v2/RHEL8/rhel-8.oval.xml.bz2 | bzip2 --decompress > rhel-8.oval.xml

2. Scan a remote system for vulnerabilities and save the results to a file:

   # oscap-ssh <username>@<hostname> <port> oval eval --report <scan-report.html> rhel-8.oval.xml

   Replace:

   • <username>@<hostname> with the user name and host name of the remote system.
   • <port> with the port number through which you can access the remote system, for example, 22.
   • <scan-report.html> with the file name where oscap saves the scan results.

Procedure

1. List all available files with security compliance profiles provided by the SCAP Security Guide project:

   $ ls /usr/share/xml/scap/ssg/content/
   ssg-firefox-cpe-dictionary.xml  ssg-rhel6-ocil.xml
   ssg-firefox-cpe-oval.xml        ssg-rhel6-oval.xml
   …
   ssg-rhel6-ds-1.2.xml          ssg-rhel8-oval.xml
   ssg-rhel8-ds.xml              ssg-rhel8-xccdf.xml
   …

2. Display detailed information about a selected data stream using the oscap info subcommand. XML files containing data streams are indicated by the -ds string in their names. In the Profiles section, you can find a list of available profiles and their IDs:

   $ oscap info /usr/share/xml/scap/ssg/content/ssg-rhel8-ds.xml
   Profiles:
   …
     Title: Health Insurance Portability and Accountability Act (HIPAA)
       Id: xccdf_org.ssgproject.content_profile_hipaa
     Title: PCI-DSS v3.2.1 Control Baseline for Red Hat Enterprise Linux 8
       Id: xccdf_org.ssgproject.content_profile_pci-dss
     Title: OSPP - Protection Profile for General Purpose Operating Systems
       Id: xccdf_org.ssgproject.content_profile_ospp
   …

3. Select a profile from the data stream file and display additional details about the selected profile. To do so, use oscap info with the --profile option followed by the last section of the ID displayed in the output of the previous command. For example, the ID of the HIPPA profile is xccdf_org.ssgproject.content_profile_hipaa, and the value for the --profile option is hipaa:

   $ oscap info --profile hipaa /usr/share/xml/scap/ssg/content/ssg-rhel8-ds.xml
   …
   Profile
   	Title: Health Insurance Portability and Accountability Act (HIPAA)
   
   	Description: The HIPAA Security Rule establishes U.S. national standards to protect individuals’ electronic personal health information that is created, received, used, or maintained by a covered entity.
   …

Procedure

1. Scan the local system for compliance with the selected profile and save the scan results to a file:

   $ oscap xccdf eval --report <scan-report.html> --profile <profileID> /usr/share/xml/scap/ssg/content/ssg-rhel8-ds.xml

   Replace:

   • <scan-report.html> with the file name where oscap saves the scan results.
   • <profileID> with the profile ID with which the system should comply, for example, hipaa.

2. Optional: Scan a remote system for compliance with the selected profile and save the scan results to a file:

   $ oscap-ssh <username>@<hostname> <port> xccdf eval --report <scan-report.html> --profile <profileID> /usr/share/xml/scap/ssg/content/ssg-rhel8-ds.xml

   Replace:

   • <username>@<hostname> with the user name and host name of the remote system.
   • <port> with the port number through which you can access the remote system.
   • <scan-report.html> with the file name where oscap saves the scan results.
   • <profileID> with the profile ID with which the system should comply, for example, hipaa.

Procedure

1. To run SCAP Workbench from the GNOME Classic desktop environment, press the Super key to enter the Activities Overview, type scap-workbench, and then press Enter. Alternatively, use:

   $ scap-workbench &

2. Select a security policy using either of the following options:

   • Load Content button on the starting window
   • Open content from SCAP Security Guide

   • Open Other Content in the File menu, and search the respective XCCDF, SCAP RPM, or data stream file.

     

3. You can allow automatic correction of the system configuration by selecting the Remediate check box. With this option enabled, SCAP Workbench attempts to change the system configuration in accordance with the security rules applied by the policy. This process should fix the related checks that fail during the system scan.

   Warning

   If not used carefully, running the system evaluation with the Remediate option enabled might render the system non-functional. Red Hat does not provide any automated method to revert changes made by security-hardening remediations. Remediations are supported on RHEL systems in the default configuration. If your system has been altered after the installation, running remediation might not make it compliant with the required security profile.

4. Scan your system with the selected profile by clicking the Scan button.

   
5. To store the scan results in form of an XCCDF, ARF, or HTML file, click the Save Results combo box. Choose the HTML Report option to generate the scan report in human-readable format. The XCCDF and ARF (data stream) formats are suitable for further automatic processing. You can repeatedly choose all three options.
6. To export results-based remediations to a file, use the Generate remediation role pop-up menu.

Procedure

1. Run SCAP Workbench, and select the profile to customize by using either Open content from SCAP Security Guide or Open Other Content in the File menu.

2. To adjust the selected security profile according to your needs, click the Customize button.

   This opens the new Customization window that enables you to modify the currently selected profile without changing the original data stream file. Choose a new profile ID.

   
3. Find a rule to modify using either the tree structure with rules organized into logical groups or the Search field.

4. Include or exclude rules using check boxes in the tree structure, or modify values in rules where applicable.

   
5. Confirm the changes by clicking the OK button.

6. To store your changes permanently, use one of the following options:

   • Save a customization file separately by using Save Customization Only in the File menu.

   • Save all security content at once by Save All in the File menu.

     If you select the Into a directory option, SCAP Workbench saves both the data stream file and the customization file to the specified location. You can use this as a backup solution.

     By selecting the As RPM option, you can instruct SCAP Workbench to create an RPM package containing the data stream file and the customization file. This is useful for distributing the security content to systems that cannot be scanned remotely, and for delivering the content for further processing.

Procedure

1. Install the aide package:

   # yum install aide

2. Generate an initial database:

   # aide --init
   Start timestamp: 2024-07-08 10:39:23 -0400 (AIDE 0.16)
   AIDE initialized database at /var/lib/aide/aide.db.new.gz
   
   Number of entries:	55856
   
   ---------------------------------------------------
   The attributes of the (uncompressed) database(s):
   ---------------------------------------------------
   
   /var/lib/aide/aide.db.new.gz
   …
     SHA512   : mZaWoGzL2m6ZcyyZ/AXTIowliEXWSZqx
                IFYImY4f7id4u+Bq8WeuSE2jasZur/A4
                FPBFaBkoCFHdoE/FW/V94Q==

3. Optional: In the default configuration, the aide --init command checks just a set of directories and files defined in the /etc/aide.conf file. To include additional directories or files in the AIDE database, and to change their watched parameters, edit /etc/aide.conf accordingly.

4. To start using the database, remove the .new substring from the initial database file name:

   # mv /var/lib/aide/aide.db.new.gz /var/lib/aide/aide.db.gz

5. Optional: To change the location of the AIDE database, edit the /etc/aide.conf file and modify the DBDIR value. For additional security, store the database, configuration, and the /usr/sbin/aide binary file in a secure location such as a read-only media.

Procedure

1. To initiate a manual check:

   # aide --check
   Start timestamp: 2024-07-08 10:43:46 -0400 (AIDE 0.16)
   AIDE found differences between database and filesystem!!
   
   Summary:
     Total number of entries:	55856
     Added entries:		0
     Removed entries:		0
     Changed entries:		1
   
   ---------------------------------------------------
   Changed entries:
   ---------------------------------------------------
   
   f   ...      ..S : /root/.viminfo
   
   ---------------------------------------------------
   Detailed information about changes:
   ---------------------------------------------------
   
   File: /root/.viminfo
     SELinux  : system_u:object_r:admin_home_t:s | unconfined_u:object_r:admin_home
                0                                | _t:s0
   …

2. At a minimum, configure the system to run AIDE weekly. Optimally, run AIDE daily. For example, to schedule a daily execution of AIDE at 04:05 a.m. by using the cron command, add the following line to the /etc/crontab file:

    05 4 * * * root /usr/sbin/aide --check

Procedure

1. Update your baseline AIDE database:

   # aide --update

   The aide --update command creates the /var/lib/aide/aide.db.new.gz database file.

2. To start using the updated database for integrity checks, remove the .new substring from the file name.

Procedure

1. Unmount all file systems on the device that you plan to encrypt, for example:

   # umount /dev/mapper/vg00-lv00

2. Make free space for storing a LUKS header. Use one of the following options that suits your scenario:

   • In the case of encrypting a logical volume, you can extend the logical volume without resizing the file system. For example:

     # lvextend -L+32M /dev/mapper/vg00-lv00

   • Extend the partition by using partition management tools, such as parted.
   • Shrink the file system on the device. You can use the resize2fs utility for the ext2, ext3, or ext4 file systems. Note that you cannot shrink the XFS file system.

3. Initialize the encryption:

   # cryptsetup reencrypt --encrypt --init-only --reduce-device-size 32M /dev/mapper/vg00-lv00 lv00_encrypted
   
   /dev/mapper/lv00_encrypted is now active and ready for online encryption.

4. Mount the device:

   # mount /dev/mapper/lv00_encrypted /mnt/lv00_encrypted

5. Add an entry for a persistent mapping to the /etc/crypttab file:

   1. Find the luksUUID:

      # cryptsetup luksUUID /dev/mapper/vg00-lv00
      
      a52e2cc9-a5be-47b8-a95d-6bdf4f2d9325

   2. Open /etc/crypttab in a text editor of your choice and add a device in this file:

      $ vi /etc/crypttab
      
      lv00_encrypted UUID=a52e2cc9-a5be-47b8-a95d-6bdf4f2d9325 none

      Replace a52e2cc9-a5be-47b8-a95d-6bdf4f2d9325 with your device’s luksUUID.

   3. Refresh initramfs with dracut:

      $ dracut -f --regenerate-all

6. Add an entry for a persistent mounting to the /etc/fstab file:

   1. Find the file system’s UUID of the active LUKS block device:

      $ blkid -p /dev/mapper/lv00_encrypted
      
      /dev/mapper/lv00-encrypted: UUID="37bc2492-d8fa-4969-9d9b-bb64d3685aa9" BLOCK_SIZE="4096" TYPE="xfs" USAGE="filesystem"

   2. Open /etc/fstab in a text editor of your choice and add a device in this file, for example:

      $ vi /etc/fstab
      
      UUID=37bc2492-d8fa-4969-9d9b-bb64d3685aa9 /home auto rw,user,auto 0

      Replace 37bc2492-d8fa-4969-9d9b-bb64d3685aa9 with your file system’s UUID.

7. Resume the online encryption:

   # cryptsetup reencrypt --resume-only /dev/mapper/vg00-lv00
   
   Enter passphrase for /dev/mapper/vg00-lv00:
   Auto-detected active dm device 'lv00_encrypted' for data device /dev/mapper/vg00-lv00.
   Finished, time 00:31.130, 10272 MiB written, speed 330.0 MiB/s

Verification

1. Verify if the existing data was encrypted:

   # cryptsetup luksDump /dev/mapper/vg00-lv00
   
   LUKS header information
   Version: 2
   Epoch: 4
   Metadata area: 16384 [bytes]
   Keyslots area: 16744448 [bytes]
   UUID: a52e2cc9-a5be-47b8-a95d-6bdf4f2d9325
   Label: (no label)
   Subsystem: (no subsystem)
   Flags: (no flags)
   
   Data segments:
     0: crypt
   	offset: 33554432 [bytes]
   	length: (whole device)
   	cipher: aes-xts-plain64
   [...]

2. View the status of the encrypted blank block device:

   # cryptsetup status lv00_encrypted
   
   /dev/mapper/lv00_encrypted is active and is in use.
     type:    LUKS2
     cipher:  aes-xts-plain64
     keysize: 512 bits
     key location: keyring
     device:  /dev/mapper/vg00-lv00

Procedure

1. Unmount all file systems on the device, for example:

   # umount /dev/<nvme0n1p1>

   Replace <nvme0n1p1> with the device identifier corresponding to the partition you want to unmount.

2. Initialize the encryption:

   # cryptsetup reencrypt --encrypt --init-only --header </home/header> /dev/<nvme0n1p1> <nvme_encrypted>
   
   WARNING!
   ========
   Header file does not exist, do you want to create it?
   
   Are you sure? (Type 'yes' in capital letters): YES
   Enter passphrase for </home/header>:
   Verify passphrase:
   /dev/mapper/<nvme_encrypted> is now active and ready for online encryption.

   Replace:

   • </home/header> with a path to the file with a detached LUKS header. The detached LUKS header has to be accessible to unlock the encrypted device later.
   • <nvme_encrypted> with the name of the device mapper that is created after encryption.

3. Mount the device:

   # mount /dev/mapper/<nvme_encrypted> /mnt/<nvme_encrypted>

4. Add an entry for a persistent mapping to the /etc/crypttab file:

   # <nvme_encrypted> /dev/disk/by-id/<nvme-partition-id> none header=</home/header>

   Replace <nvme-partition-id> with the identifier of the NVMe partition.

5. Regenerate initramfs with dracut:

   # dracut -f --regenerate-all -v

6. Add an entry for a persistent mounting to the /etc/fstab file:

   1. Find the file system’s UUID of the active LUKS block device:

      $ blkid -p /dev/mapper/<nvme_encrypted>
      
      /dev/mapper/<nvme_encrypted>: UUID="37bc2492-d8fa-4969-9d9b-bb64d3685aa9" BLOCK_SIZE="4096" TYPE="xfs" USAGE="filesystem"

   2. Open /etc/fstab in a text editor and add a device in this file, for example:

      UUID=<file_system_UUID> /home auto rw,user,auto 0

      Replace <file_system_UUID> with the file system’s UUID found in the previous step.

7. Resume the online encryption:

   # cryptsetup reencrypt --resume-only --header </home/header> /dev/<nvme0n1p1>
   
   Enter passphrase for /dev/<nvme0n1p1>:
   Auto-detected active dm device '<nvme_encrypted>' for data device /dev/<nvme0n1p1>.
   Finished, time 00m51s,   10 GiB written, speed 198.2 MiB/s

Verification

1. Verify if the existing data on a block device using LUKS2 with a detached header is encrypted:

   # cryptsetup luksDump </home/header>
   
   LUKS header information
   Version:       	2
   Epoch:         	88
   Metadata area: 	16384 [bytes]
   Keyslots area: 	16744448 [bytes]
   UUID:          	c4f5d274-f4c0-41e3-ac36-22a917ab0386
   Label:         	(no label)
   Subsystem:     	(no subsystem)
   Flags:       	(no flags)
   
   Data segments:
     0: crypt
   	offset: 0 [bytes]
   	length: (whole device)
   	cipher: aes-xts-plain64
   	sector: 512 [bytes]
   [...]

2. View the status of the encrypted blank block device:

   # cryptsetup status <nvme_encrypted>
   
   /dev/mapper/<nvme_encrypted> is active and is in use.
     type:    LUKS2
     cipher:  aes-xts-plain64
     keysize: 512 bits
     key location: keyring
     device:  /dev/<nvme0n1p1>

Procedure

1. Setup a partition as an encrypted LUKS partition:

   # cryptsetup luksFormat /dev/nvme0n1p1
   
   WARNING!
   ========
   This will overwrite data on /dev/nvme0n1p1 irrevocably.
   Are you sure? (Type 'yes' in capital letters): YES
   Enter passphrase for /dev/nvme0n1p1:
   Verify passphrase:

2. Open an encrypted LUKS partition:

   # cryptsetup open /dev/nvme0n1p1 nvme0n1p1_encrypted
   
   Enter passphrase for /dev/nvme0n1p1:

   This unlocks the partition and maps it to a new device by using the device mapper. To not overwrite the encrypted data, this command alerts the kernel that the device is an encrypted device and addressed through LUKS by using the /dev/mapper/device_mapped_name path.

3. Create a file system to write encrypted data to the partition, which must be accessed through the device mapped name:

   # mkfs -t ext4 /dev/mapper/nvme0n1p1_encrypted

4. Mount the device:

   # mount /dev/mapper/nvme0n1p1_encrypted mount-point

Verification

1. Verify if the blank block device is encrypted:

   # cryptsetup luksDump /dev/nvme0n1p1
   
   LUKS header information
   Version:       	2
   Epoch:         	3
   Metadata area: 	16384 [bytes]
   Keyslots area: 	16744448 [bytes]
   UUID:          	34ce4870-ffdf-467c-9a9e-345a53ed8a25
   Label:         	(no label)
   Subsystem:     	(no subsystem)
   Flags:       	(no flags)
   
   Data segments:
     0: crypt
   	offset: 16777216 [bytes]
   	length: (whole device)
   	cipher: aes-xts-plain64
   	sector: 512 [bytes]
   [...]

2. View the status of the encrypted blank block device:

   # cryptsetup status nvme0n1p1_encrypted
   
   /dev/mapper/nvme0n1p1_encrypted is active and is in use.
     type:    LUKS2
     cipher:  aes-xts-plain64
     keysize: 512 bits
     key location: keyring
     device:  /dev/nvme0n1p1
     sector size:  512
     offset:  32768 sectors
     size:    20938752 sectors
     mode:    read/write

Procedure

1. Log in to the RHEL 8 web console.

   For details, see Logging in to the web console.

2. In the panel, click Storage.
3. In the Storage table, click the menu button ⋮ for the storage device you want to encrypt and click Format.
4. In the Encryption field, select the encryption specification, LUKS1 or LUKS2.
5. Set and confirm your new passphrase.
6. Optional: Modify further encryption options.
7. Finalize formatting settings.
8. Click Format.

Procedure

1. Log in to the RHEL 8 web console.

   For details, see Logging in to the web console.

2. In the panel, click Storage.
3. In the Storage table, select the disk with encrypted data.
4. On the disk page, scroll to the Keys section and click the edit button.

5. In the Change passphrase dialog window:

   1. Enter your current passphrase.
   2. Enter your new passphrase.
   3. Confirm your new passphrase.
6. Click Save.

Procedure

1. Change the existing passphrase on the LUKS encrypted device:

   # cryptsetup luksChangeKey /dev/<device_ID>

   Replace <device_ID> with the device designator, for example, sda.

   If you have multiple key slots configured, you can specify the slot to work with:

   # cryptsetup luksChangeKey /dev/<device_ID> --key-slot <slot_number>

   Replace <slot_number> with the number of the key slot you want to modify.

2. Insert the current passphrase and the new passphrase:

   Enter passphrase to be changed:
   Enter new passphrase:
   Verify passphrase:

3. Validate the new passphrase:

   # cryptsetup --verbose open --test-passphrase /dev/<device_ID>

Verification

1. Verify that the new passphrase can unlock the device:

   Enter passphrase for /dev/<device_ID>:
   Key slot <slot_number> unlocked.
   Command successful.

Procedure

1. Store your sensitive variables in an encrypted file:

   1. Create the vault:

      $ ansible-vault create ~/vault.yml
      New Vault password: <vault_password>
      Confirm New Vault password: <vault_password>

   2. After the ansible-vault create command opens an editor, enter the sensitive data in the <key>: <value> format:

      luks_password: <password>

   3. Save the changes, and close the editor. Ansible encrypts the data in the vault.

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

   ---
   - name: Manage local storage
     hosts: managed-node-01.example.com
     vars_files:
       - ~/vault.yml
     tasks:
       - name: Create and configure a volume encrypted with LUKS
         ansible.builtin.include_role:
           name: redhat.rhel_system_roles.storage
         vars:
           storage_volumes:
             - name: barefs
               type: disk
               disks:
                 - sdb
               fs_type: xfs
               fs_label: <label>
               mount_point: /mnt/data
               encryption: true
               encryption_password: "{{ luks_password }}"

   For details about all variables used in the playbook, see the /usr/share/ansible/roles/rhel-system-roles.storage/README.md file on the control node.

3. Validate the playbook syntax:

   $ ansible-playbook --ask-vault-pass --syntax-check ~/playbook.yml

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

4. Run the playbook:

   $ ansible-playbook --ask-vault-pass ~/playbook.yml

Verification

1. Find the luksUUID value of the LUKS encrypted volume:

   # ansible managed-node-01.example.com -m command -a 'cryptsetup luksUUID /dev/sdb'
   
   4e4e7970-1822-470e-b55a-e91efe5d0f5c

2. View the encryption status of the volume:

   # ansible managed-node-01.example.com -m command -a 'cryptsetup status luks-4e4e7970-1822-470e-b55a-e91efe5d0f5c'
   
   /dev/mapper/luks-4e4e7970-1822-470e-b55a-e91efe5d0f5c is active and is in use.
     type:    LUKS2
     cipher:  aes-xts-plain64
     keysize: 512 bits
     key location: keyring
     device:  /dev/sdb
   ...

3. Verify the created LUKS encrypted volume:

   # ansible managed-node-01.example.com -m command -a 'cryptsetup luksDump /dev/sdb'
   
   LUKS header information
   Version:        2
   Epoch:          3
   Metadata area:  16384 [bytes]
   Keyslots area:  16744448 [bytes]
   UUID:           4e4e7970-1822-470e-b55a-e91efe5d0f5c
   Label:          (no label)
   Subsystem:      (no subsystem)
   Flags:          (no flags)
   
   Data segments:
     0: crypt
           offset: 16777216 [bytes]
           length: (whole device)
           cipher: aes-xts-plain64
           sector: 512 [bytes]
   ...

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 and exit the editor. In the default vi editor, you can do that by pressing Esc to switch into command mode, entering :wq, and pressing Enter.

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. Log in to the RHEL 8 web console.

   For details, see Logging in to the web console.

2. Switch to administrative access, provide your credentials, and click Storage. In the Storage table, click the disk that contains an encrypted volume you plan to add to unlock automatically.

3. In the following page with details of the selected disk, click + in the Keys section to add a Tang key:

   

4. 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.

5. 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
   x100_1k6GPiDOaMlL3WbpCjHOy9ul1bSfdhI3M08wO0

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

   
7. 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-luks
   lrwxrwxrwx   1 root     root           48 Jan  4 02:56 etc/systemd/system/cryptsetup.target.wants/clevis-luks-askpass.path -> /usr/lib/systemd/system/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. 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:

   1. Install the clevis-dracut package:

      # yum install clevis-dracut

   2. Regenerate the initial RAM disk:

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

   3. Alternatively, create a .conf file in the /etc/dracut.conf.d/ directory, and add the hostonly_cmdline=yes option to the file. Then, you can use dracut without --hostonly-cmdline, for example:

      # echo "hostonly_cmdline=yes" > /etc/dracut.conf.d/clevis.conf
      # dracut -fv --regenerate-all

   4. 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"

Verification

1. 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"}'

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

   # lsinitrd | grep clevis-luks
   lrwxrwxrwx   1 root     root           48 Jan  4 02:56 etc/systemd/system/cryptsetup.target.wants/clevis-luks-askpass.path -> /usr/lib/systemd/system/clevis-luks-askpass.path
   …

Procedure

1. You can provide your static network configuration as a value for the kernel-cmdline option in a dracut command, for example:

   # dracut -fv --regenerate-all --kernel-cmdline "ip=192.0.2.10::192.0.2.1:255.255.255.0::ens3:none nameserver=192.0.2.100"

2. Alternatively, create a .conf file in the /etc/dracut.conf.d/ directory with the static network information and then, regenerate the initial RAM disk image:

   # cat /etc/dracut.conf.d/static_ip.conf
   kernel_cmdline="ip=192.0.2.10::192.0.2.1:255.255.255.0::ens3:none nameserver=192.0.2.100"
   # dracut -fv --regenerate-all

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"}'

      Important

      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 upgrading the shim-x64 package, see the Red Hat Knowledgebase solution Clevis TPM2 no longer decrypts LUKS devices after a restart.

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. Optional: To ensure that you can unlock the encrypted volume manually when required, add a strong passphrase before you remove the temporary passphrase. For more information, see the Red Hat Knowledgebase solution How to add a passphrase, key, or keyfile to an existing LUKS device.

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.