Procedure

1. Add the fips=1 option to the kernel command line during the system installation.
2. During the software selection stage, do not install any third-party software.
3. After the installation, the system starts in FIPS mode automatically.

Procedure

1. To switch the system-wide cryptographic policy to the LEGACY level, enter the following command as root:

   # update-crypto-policies --set LEGACY
   Setting system policy to LEGACY

Procedure

1. Log in to the web console. For more information, see Logging in to the web console.

2. In the Configuration card of the Overview page, click your current policy value next to Crypto policy.

   

3. In the Change crypto policy dialog window, click on the policy you want to start using on your system.

   

4. Click the Apply and reboot button.

Procedure

1. To switch the system to FIPS mode:

   # fips-mode-setup --enable
   Kernel initramdisks are being regenerated. This might take some time.
   Setting system policy to FIPS
   Note: System-wide crypto policies are applied on application start-up.
   It is recommended to restart the system for the change of policies
   to fully take place.
   FIPS mode will be enabled.
   Please reboot the system for the setting to take effect.

2. Restart your system to allow the kernel to switch to FIPS mode:

   # reboot

Procedure

1. Checkout to the /etc/crypto-policies/policies/modules/ directory:

   # cd /etc/crypto-policies/policies/modules/

2. Create subpolicies for your adjustments, for example:

   # touch MYCRYPTO-1.pmod
   # touch SCOPES-AND-WILDCARDS.pmod

   Important

   Use upper-case letters in file names of policy modules.

3. Open the policy modules in a text editor of your choice and insert options that modify the system-wide cryptographic policy, for example:

   # vi MYCRYPTO-1.pmod

   min_rsa_size = 3072
   hash = SHA2-384 SHA2-512 SHA3-384 SHA3-512

   # vi SCOPES-AND-WILDCARDS.pmod

   # Disable the AES-128 cipher, all modes
   cipher = -AES-128-*
   
   # Disable CHACHA20-POLY1305 for the TLS protocol (OpenSSL, GnuTLS, NSS, and OpenJDK)
   cipher@TLS = -CHACHA20-POLY1305
   
   # Allow using the FFDHE-1024 group with the SSH protocol (libssh and OpenSSH)
   group@SSH = FFDHE-1024+
   
   # Disable all CBC mode ciphers for the SSH protocol (libssh and OpenSSH)
   cipher@SSH = -*-CBC
   
   # Allow the AES-256-CBC cipher in applications using libssh
   cipher@libssh = AES-256-CBC+

4. Save the changes in the module files.

5. Apply your policy adjustments to the DEFAULT system-wide cryptographic policy level:

   # update-crypto-policies --set DEFAULT:MYCRYPTO-1:SCOPES-AND-WILDCARDS

6. To make your cryptographic settings effective for already running services and applications, restart the system:

   # reboot

Procedure

1. Apply the SHA1 subpolicy to the DEFAULT cryptographic policy:

   # update-crypto-policies --set DEFAULT:SHA1
   Setting system policy to DEFAULT:SHA1
   Note: System-wide crypto policies are applied on application start-up.
   It is recommended to restart the system for the change of policies
   to fully take place.

2. Restart the system:

   # reboot

Procedure

1. Create a policy file for your customizations:

   # cd /etc/crypto-policies/policies/
   # touch MYPOLICY.pol

   Alternatively, start by copying one of the four predefined policy levels:

   # cp /usr/share/crypto-policies/policies/DEFAULT.pol /etc/crypto-policies/policies/MYPOLICY.pol

2. Edit the file with your custom cryptographic policy in a text editor of your choice to fit your requirements, for example:

   # vi /etc/crypto-policies/policies/MYPOLICY.pol

3. Switch the system-wide cryptographic policy to your custom level:

   # update-crypto-policies --set MYPOLICY

4. To make your cryptographic settings effective for already running services and applications, restart the system:

   # reboot

Procedure

1. Create a new playbook.yml file with the following content:

   ---
   - hosts: all
     tasks:
     - name: Configure crypto policies
       include_role:
         name: rhel-system-roles.crypto_policies
       vars:
         - crypto_policies_policy: FUTURE
         - crypto_policies_reboot_ok: true

   You can replace the FUTURE value with your preferred crypto policy, for example: DEFAULT, LEGACY, and FIPS:OSPP.

   The crypto_policies_reboot_ok: true variable causes the system to reboot after the System Role changes the cryptographic policy.

   For more details, see crypto_policies System Role variables and facts .

2. Optional: Verify playbook syntax.

   # ansible-playbook --syntax-check playbook.yml

3. Run the playbook on your inventory file:

   # ansible-playbook -i inventory_file playbook.yml

Verification

1. On the control node, create another playbook named, for example, verify_playbook.yml:

   - hosts: all
     tasks:
    - name: Verify active crypto policy
      include_role:
        name: rhel-system-roles.crypto_policies
   
    - debug:
        var: crypto_policies_active

   This playbook does not change any configurations on the system, only reports the active policy on the managed nodes.

2. Run the playbook on the same inventory file:

   # ansible-playbook -i inventory_file verify_playbook.yml
   
   TASK [debug] **************************
   ok: [host] => {
       "crypto_policies_active": "FUTURE"
   }

   The "crypto_policies_active": variable shows the policy active on the managed node.

Procedure

1. List all keys provided by the OpenSC PKCS #11 module including their PKCS #11 URIs and save the output to the keys.pub file:

   $ ssh-keygen -D pkcs11: > keys.pub
   $ ssh-keygen -D pkcs11:
   ssh-rsa AAAAB3NzaC1yc2E...KKZMzcQZzx pkcs11:id=%02;object=SIGN%20pubkey;token=SSH%20key;manufacturer=piv_II?module-path=/usr/lib64/pkcs11/opensc-pkcs11.so
   ecdsa-sha2-nistp256 AAA...J0hkYnnsM= pkcs11:id=%01;object=PIV%20AUTH%20pubkey;token=SSH%20key;manufacturer=piv_II?module-path=/usr/lib64/pkcs11/opensc-pkcs11.so

2. To enable authentication using a smart card on a remote server (example.com), transfer the public key to the remote server. Use the ssh-copy-id command with keys.pub created in the previous step:

   $ ssh-copy-id -f -i keys.pub username@example.com

3. To connect to example.com using the ECDSA key from the output of the ssh-keygen -D command in step 1, you can use just a subset of the URI, which uniquely references your key, for example:

   $ ssh -i "pkcs11:id=%01?module-path=/usr/lib64/pkcs11/opensc-pkcs11.so" example.com
   Enter PIN for 'SSH key':
   [example.com] $

4. You can use the same URI string in the ~/.ssh/config file to make the configuration permanent:

   $ cat ~/.ssh/config
   IdentityFile "pkcs11:id=%01?module-path=/usr/lib64/pkcs11/opensc-pkcs11.so"
   $ ssh example.com
   Enter PIN for 'SSH key':
   [example.com] $

   Because OpenSSH uses the p11-kit-proxy wrapper and the OpenSC PKCS #11 module is registered to PKCS#11 Kit, you can simplify the previous commands:

   $ ssh -i "pkcs11:id=%01" example.com
   Enter PIN for 'SSH key':
   [example.com] $

Procedure

1. Create a new file in the /etc/polkit-1/rules.d/ directory:

   # touch /etc/polkit-1/rules.d/00-test.rules

2. Edit the file in an editor of your choice, for example:

   # vi /etc/polkit-1/rules.d/00-test.rules

3. Insert the following lines:

   polkit.addRule(function(action, subject) {
     if (action.id == "org.debian.pcsc-lite.access_pcsc" ||
     	action.id == "org.debian.pcsc-lite.access_card") {
   	polkit.log("action=" + action);
   	polkit.log("subject=" + subject);
     }
   });

   Save the file, and exit the editor.

4. Restart the pcscd and polkit services:

   # systemctl restart pcscd.service pcscd.socket polkit.service

Verification

1. Make an authorization request for pcscd. For example, open the Firefox web browser or use the pkcs11-tool -L command provided by the opensc package.

2. Display the extended log entries, for example:

   # journalctl -u polkit --since "1 hour ago"
   polkitd[1224]: <no filename>:4: action=[Action id='org.debian.pcsc-lite.access_pcsc']
   polkitd[1224]: <no filename>:5: subject=[Subject pid=2020481 user=user' groups=user,wheel,mock,wireshark seat=null session=null local=true active=true]

Procedure

1. Use the oscap command with the --remediate option:

   # oscap xccdf eval --profile hipaa --remediate /usr/share/xml/scap/ssg/content/ssg-rhel9-ds.xml

2. Restart your system.

Verification

1. Evaluate compliance of the system with the HIPAA profile, and save scan results in the hipaa_report.html file:

   $ oscap xccdf eval --report hipaa_report.html --profile hipaa /usr/share/xml/scap/ssg/content/ssg-rhel9-ds.xml

Procedure

1. Remediate your system to align with HIPAA using Ansible:

   # ansible-playbook -i localhost, -c local /usr/share/scap-security-guide/ansible/rhel9-playbook-hipaa.yml

2. Restart the system.

Verification

1. Evaluate compliance of the system with the HIPAA profile, and save scan results in the hipaa_report.html file:

   # oscap xccdf eval --profile hipaa --report hipaa_report.html /usr/share/xml/scap/ssg/content/ssg-rhel9-ds.xml

Procedure

1. Scan the system and save the results:

   # oscap xccdf eval --profile hipaa --results <hipaa-results.xml> /usr/share/xml/scap/ssg/content/ssg-rhel9-ds.xml

2. Find the value of the result ID in the file with the results:

   # oscap info <hipaa-results.xml>

3. Generate an Ansible playbook based on the file generated in step 1:

   # oscap xccdf generate fix --fix-type ansible --result-id <xccdf_org.open-scap_testresult_xccdf_org.ssgproject.content_profile_hipaa> --output <hipaa-remediations.yml> <hipaa-results.xml>

4. Review the generated file, which contains the Ansible remediations for rules that failed during the scan performed in step 1. After reviewing this generated file, you can apply it by using the ansible-playbook <hipaa-remediations.yml> command.

Procedure

1. Use the oscap command to scan the system and to save the results to an XML file. In the following example, oscap evaluates the system against the hipaa profile:

   # oscap xccdf eval --profile hipaa --results <hipaa-results.xml> /usr/share/xml/scap/ssg/content/ssg-rhel9-ds.xml

2. Find the value of the result ID in the file with the results:

   # oscap info <hipaa-results.xml>

3. Generate a Bash script based on the results file generated in step 1:

   # oscap xccdf generate fix --fix-type bash --result-id <xccdf_org.open-scap_testresult_xccdf_org.ssgproject.content_profile_hipaa> --output <hipaa-remediations.sh> <hipaa-results.xml>

4. The <hipaa-remediations.sh> file contains remediations for rules that failed during the scan performed in step 1. After reviewing this generated file, you can apply it with the ./<hipaa-remediations.sh> command when you are in the same directory as this file.

Procedure

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

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

2. Get the ID of a container or a container image, for example:

   # podman images
   REPOSITORY                            TAG      IMAGE ID       CREATED       SIZE
   registry.access.redhat.com/ubi9/ubi   latest   096cae65a207   7 weeks ago   239 MB

3. Scan the container or the container image for vulnerabilities and save results to the vulnerability.html file:

   # oscap-podman 096cae65a207 oval eval --report vulnerability.html rhel-9.oval.xml

   Note that the oscap-podman command requires root privileges, and the ID of a container is the first argument.

Procedure

1. Get the ID of a container or a container image, for example:

   # podman images
   REPOSITORY                            TAG      IMAGE ID       CREATED       SIZE
   registry.access.redhat.com/ubi9/ubi   latest   096cae65a207   7 weeks ago   239 MB

2. Evaluate the compliance of the container image with the HIPAA profile and save scan results into the report.html HTML file

   # oscap-podman 096cae65a207 xccdf eval --report report.html --profile hipaa /usr/share/xml/scap/ssg/content/ssg-rhel9-ds.xml

   Replace 096cae65a207 with the ID of your container image and the hipaa value with ospp or pci-dss if you assess security compliance with the OSPP or PCI-DSS baseline. Note that the oscap-podman command requires root privileges.

Procedure

1. Install the Keylime verifier:

   # dnf install keylime-verifier

2. Define the IP address and port of the registrar and verifier in the verifier configuration.

   1. Create a new .conf file in the /etc/keylime/verifier.conf.d/ directory, for example, /etc/keylime/verifier.conf.d/00-verifier-ip.conf, with the following content:

      [verifier]
      ip = <verifier_IP_address>

      • Replace <verifier_IP_address> with the verifier’s IP address. Alternatively, use ip = * or ip = 0.0.0.0 to bind the verifier to all available IP addresses.
      • Optionally, you can also change the verifier’s port from the default value 8881 by using the port = <verifier_port> option.

   2. Create a new .conf file in the /etc/keylime/verifier.conf.d/ directory, for example, /etc/keylime/verifier.conf.d/00-registrar-ip.conf, with the following content:

      [verifier]
      registrar_ip = <registrar_IP_address>

      • Replace <registrar_IP_address> with the registrar’s IP address.
      • If the registrar uses a different port than the default value 8891, add the registrar_port = <registrar_port> setting.

3. Optional: Configure the verifier’s database for the list of agents. The default configuration uses an SQLite database in the verifiers’s /var/lib/keylime/cv_data.sqlite/ directory. You can define a different database by creating a new .conf file in the /etc/keylime/verifier.conf.d/ directory, for example, /etc/keylime/verifier.conf.d/00-db-url.conf, with the following content:

   [verifier]
   database_url = <protocol>://<name>:<password>@<ip_address_or_hostname>/<properties>

   Replace <protocol>://<name>:<password>@<ip_address_or_hostname>/<properties> with the URL of the database, for example, postgresql://verifier:UQ?nRNY9g7GZzN7@198.51.100.1/verifierdb.

   Ensure that the credentials you use have the permissions for Keylime to create the database structure.

4. Add certificates and keys to the verifier. You can either let Keylime generate them, or use existing keys and certificates:

   • With the default tls_dir = generate option, Keylime generates new certificates for the verifier, registrar, and tenant in the /var/lib/keylime/cv_ca/ directory.

   • To load existing keys and certificates in the configuration, define their location in the verifier configuration.

     Note

     Certificates must be accessible by the keylime user, under which the Keylime services are running.

     Create a new .conf file in the /etc/keylime/verifier.conf.d/ directory, for example, /etc/keylime/verifier.conf.d/00-keys-and-certs.conf, with the following content:

     [verifier]
     tls_dir = /var/lib/keylime/cv_ca
     server_key = </path/to/server_key>
     server_key_password = <passphrase1>
     server_cert = </path/to/server_cert>
     trusted_client_ca = ['</path/to/ca/cert1>', '</path/to/ca/cert2>']
     client_key = </path/to/client_key>
     client_key_password = <passphrase2>
     client_cert = </path/to/client_cert>
     trusted_server_ca = ['</path/to/ca/cert3>', '</path/to/ca/cert4>']

     Note

     Use absolute paths to define key and certificate locations. Alternatively, relative paths are resolved from the directory defined in the tls_dir option.

5. Open the port in firewall:

   # firewall-cmd --add-port 8881/tcp
   # firewall-cmd --runtime-to-permanent

   If you use a different port, replace 8881 with the port number defined in the .conf file.

6. Start the verifier service:

   # systemctl enable --now keylime_verifier

   Note

   In the default configuration, start the keylime_verifier before starting the keylime_registrar service because the verifier creates the CA and certificates for the other Keylime components. This order is not necessary when you use custom certificates.

Procedure

1. Install the Keylime registrar:

   # dnf install keylime-registrar

2. Define the IP address and port of the registrar:

   1. Create a new .conf file in the /etc/keylime/registrar.conf.d/ directory, for example, /etc/keylime/registrar.conf.d/00-registrar-ip.conf, with the following content:

      [registrar]
      ip = <registrar_IP_address>

      • Replace <registrar_IP_address> with the registrar’s IP address. Alternatively, use ip = * or ip = 0.0.0.0 to bind the registrar to all available IP addresses.
      • Optionally, change the port to which the Keylime agents connect by using the port = option. The default value is 8890.
      • Optionally, change the TLS port to which the Keylime verifier and tenant connect by using the tls_port = option. The default value is 8891.

3. Optional: Configure the registrar’s database for the list of agents. The default configuration uses an SQLite database in the registrar’s /var/lib/keylime/reg_data.sqlite directory. You can create a new .conf file in the /etc/keylime/registrar.conf.d/ directory, for example, /etc/keylime/registrar.conf.d/00-db-url.conf, with the following content:

   [registrar]
   database_url = <protocol>://<name>:<password>@<ip_address_or_hostname>/<properties>

   Replace <protocol>://<name>:<password>@<ip_address_or_hostname>/<properties> with the URL of the database, for example, postgresql://registrar:EKYYX-bqY2?#raXm@198.51.100.1/registrardb.

   Ensure that the credentials you use have the permissions for Keylime to create the database structure.

4. Add certificates and keys to the registrar:

   • You can use the default configuration and load the keys and certificates to the /var/lib/keylime/reg_ca/ directory.

   • Alternatively, you can define the location of the keys and certificates in the configuration. Create a new .conf file in the /etc/keylime/registrar.conf.d/ directory, for example, /etc/keylime/registrar.conf.d/00-keys-and-certs.conf, with the following content:

     Important

     Do not use the tls_dir = default setting with custom CA certificates. Instead, specify a path to the location of the certificates. For more information, see RHELPLAN-157337.

     [registrar]
     tls_dir = /var/lib/keylime/reg_ca
     server_key = </path/to/server_key>
     server_key_password = <passphrase1>
     server_cert = </path/to/server_cert>
     trusted_client_ca = ['</path/to/ca/cert1>', '</path/to/ca/cert2>']

     Note

     Use absolute paths to define key and certificate locations. Alternatively, you can define a directory in the tls_dir option and use paths relative to that directory.

5. Open the ports in firewall:

   # firewall-cmd --add-port 8890/tcp --add-port 8891/tcp
   # firewall-cmd --runtime-to-permanent

   If you use a different port, replace 8890 or 8891 with the port number defined in the .conf file.

6. Start the keylime_registrar service:

   # systemctl enable --now keylime_registrar

   Note

   In the default configuration, start the keylime_verifier before starting the keylime_registrar service because the verifier creates the CA and certificates for the other Keylime components. This order is not necessary when you use custom certificates.

Procedure

1. Install the Keylime tenant:

   # dnf install keylime-tenant

2. Define the tenant’s connection to the Keylime verifier by editing the /etc/keylime/tenant.conf.d/00-verifier-ip.conf file:

   [tenant]
   verifier_ip = <verifier_ip>

   • Replace <verifier_ip> with the IP address to the verifier’s system. Alternatively, use ip = * or ip = 0.0.0.0 to bind the tenant to all available IP addresses.
   • If the verifier uses a different port than the default value 8881, add the verifier_port = <verifier_port> setting.

3. Define the tenant’s connection to the Keylime registrar by editing the /etc/keylime/tenant.conf.d/00-registrar-ip.conf file:

   [tenant]
   registrar_ip = <registrar_ip>
   registrar_port = <registrar_port>

   • Replace <registrar_ip> with the IP address to the registrar’s system.
   • If the registrar uses a different port than the default value 8891, add the registrar_port = <registrar_port> setting.

4. Add certificates and keys to the tenant:

   1. You can use the default configuration and load the keys and certificates to the /var/lib/keylime/cv_ca directory.

   2. Alternatively, you can define the location of the keys and certificates in the configuration. Create a new .conf file in the /etc/keylime/tenant.conf.d/ directory, for example, /etc/keylime/tenant.conf.d/00-keys-and-certs.conf, with the following content:

      [tenant]
      tls_dir = /var/lib/keylime/cv_ca
      client_key = tenant-key.pem
      client_key_password = <passphrase1>
      client_cert = tenant-cert.pem
      trusted_server_ca = ['/var/lib/keylime/cv_ca/cacert.pem']

      The trusted_server_ca parameter accepts paths to the verifier and registrar server CA certificate. You can provide multiple comma-separated paths, for example if the verifier and registrar use different CAs.

      Note

      Use absolute paths to define key and certificate locations. Alternatively, you can define a directory in the tls_dir option and use paths relative to that directory.

5. Optional: If the trusted platform module (TPM) endorsement key (EK) cannot be verified by using certificates in the /var/lib/keylime/tpm_cert_store directory, add the certificate to that directory. This can occur particularly when using virtual machines with emulated TPMs.

Verification

1. Check the status of the verifier:

   3 keylime_tenant -c cvstatus
   Reading configuration from ['/etc/keylime/logging.conf']
   2022-10-14 12:56:08.155 - keylime.tpm - INFO - TPM2-TOOLS Version: 5.2
   Reading configuration from ['/etc/keylime/tenant.conf']
   2022-10-14 12:56:08.157 - keylime.tenant - INFO - Setting up client TLS...
   2022-10-14 12:56:08.158 - keylime.tenant - INFO - Using default client_cert option for tenant
   2022-10-14 12:56:08.158 - keylime.tenant - INFO - Using default client_key option for tenant
   2022-10-14 12:56:08.178 - keylime.tenant - INFO - TLS is enabled.
   2022-10-14 12:56:08.178 - keylime.tenant - WARNING - Using default UUID d432fbb3-d2f1-4a97-9ef7-75bd81c00000
   2022-10-14 12:56:08.221 - keylime.tenant - INFO - Verifier at 127.0.0.1 with Port 8881 does not have agent d432fbb3-d2f1-4a97-9ef7-75bd81c00000.

   If correctly set up, and if no agent is configured, the verifier responds that it does not recognize the default agent UUID.

2. Check the status of the registrar:

   # keylime_tenant -c regstatus
   Reading configuration from ['/etc/keylime/logging.conf']
   2022-10-14 12:56:02.114 - keylime.tpm - INFO - TPM2-TOOLS Version: 5.2
   Reading configuration from ['/etc/keylime/tenant.conf']
   2022-10-14 12:56:02.116 - keylime.tenant - INFO - Setting up client TLS...
   2022-10-14 12:56:02.116 - keylime.tenant - INFO - Using default client_cert option for tenant
   2022-10-14 12:56:02.116 - keylime.tenant - INFO - Using default client_key option for tenant
   2022-10-14 12:56:02.137 - keylime.tenant - INFO - TLS is enabled.
   2022-10-14 12:56:02.137 - keylime.tenant - WARNING - Using default UUID d432fbb3-d2f1-4a97-9ef7-75bd81c00000
   2022-10-14 12:56:02.171 - keylime.registrar_client - CRITICAL - Error: could not get agent d432fbb3-d2f1-4a97-9ef7-75bd81c00000 data from Registrar Server: 404
   2022-10-14 12:56:02.172 - keylime.registrar_client - CRITICAL - Response code 404: agent d432fbb3-d2f1-4a97-9ef7-75bd81c00000 not found
   2022-10-14 12:56:02.172 - keylime.tenant - INFO - Agent d432fbb3-d2f1-4a97-9ef7-75bd81c00000 does not exist on the registrar. Please register the agent with the registrar.
   2022-10-14 12:56:02.172 - keylime.tenant - INFO - {"code": 404, "status": "Agent d432fbb3-d2f1-4a97-9ef7-75bd81c00000 does not exist on registrar 127.0.0.1 port 8891.", "results": {}}

   If correctly set up, and if no agent is configured, the registrar responds that it does not recognize the default agent UUID.

Procedure

1. Install the Keylime agent:

   # dnf install keylime-agent

   This command installs the keylime-agent-rust package.

2. Define the agent’s IP address and port in the configuration files. Create a new .conf file in the /etc/keylime/agent.conf.d/ directory, for example, /etc/keylime/agent.conf.d/00-agent-ip.conf, with the following content:

   [agent]
   ip = '<agent_ip>'

   Note

   Because the Keylime agent configuration uses the TOML format, which is different from the INI format used for configuration of the other components, the values must be in single quotation marks.

   • Replace <agent_IP_address> with the agent’s IP address. Alternatively, use ip = '*' or ip = '0.0.0.0' to bind the agent to all available IP addresses.
   • Optionally, you can also change the agent’s port from the default value 9002 by using the port = '<agent_port>' option.

3. Define the registrar’s IP address and port in the configuration files. Create a new .conf file in the /etc/keylime/agent.conf.d/ directory, for example, /etc/keylime/agent.conf.d/00-registrar-ip.conf, with the following content:

   [agent]
   registrar_ip = '<registrar_IP_address>'

   • Replace <registrar_IP_address> with the registrar’s IP address.
   • Optionally, you can also change the registrar’s port from the default value 8890 by using the registrar_port = '<registrar_port>' option.

4. Optional: Define the agent’s universally unique identifier (UUID). If it is not defined, the default UUID is used. Create a new .conf file in the /etc/keylime/agent.conf.d/ directory, for example, /etc/keylime/agent.conf.d/00-agent-uuid.conf, with the following content:

   [agent]
   uuid = '<agent_UUID>'

   • Replace <agent_UUID> with the agent’s UUID, for example d432fbb3-d2f1-4a97-9ef7-abcdef012345. You can use the uuidgen utility to generate a UUID.

5. Optional: Load existing keys and certificates for the agent. If the agent receives no server_key and server_cert, it generates its own key and a self-signed certificate.

   Important

   Do not use certificate chains. Keylime currently does not correctly use all the provided certificates during signature verification, which results in a TLS handshake failure. For more information, see RHEL-396.

   Define the location of the keys and certificates in the configuration. Create a new .conf file in the /etc/keylime/agent.conf.d/ directory, for example, /etc/keylime/agent.conf.d/00-keys-and-certs.conf, with the following content:

   [agent]
   server_key = '</path/to/server_key>'
   server_key_password = '<passphrase1>'
   server_cert = '</path/to/server_cert>'
   trusted_client_ca = '</path/to/ca/cert>'

   Note

   Use absolute paths to define key and certificate locations. The Keylime agent does not accept relative paths.

6. Open the port in firewall:

   # firewall-cmd --add-port 9002/tcp
   # firewall-cmd --runtime-to-permanent

   If you use a different port, replace 9002 with the port number defined in the .conf file.

7. Enable and start the keylime_agent service:

   # systemctl enable --now keylime_agent

8. Optional: From the system where the Keylime tenant is configured, verify that the agent is correctly configured and can connect to the registrar.

   # keylime_tenant -c regstatus --uuid <agent_uuid>
   Reading configuration from ['/etc/keylime/logging.conf']
   ...
   ==\n-----END CERTIFICATE-----\n", "ip": "127.0.0.1", "port": 9002, "regcount": 1, "operational_state": "Registered"}}}

   • Replace <agent_uuid> with the agent’s UUID.

     If the registrar and agent are correctly configured, the output displays the agent’s IP address and port, followed by "operational_state": "Registered".

9. Create a new IMA policy by entering the following content into the /etc/ima/ima-policy file:

   # PROC_SUPER_MAGIC
   dont_measure fsmagic=0x9fa0
   # SYSFS_MAGIC
   dont_measure fsmagic=0x62656572
   # DEBUGFS_MAGIC
   dont_measure fsmagic=0x64626720
   # TMPFS_MAGIC
   dont_measure fsmagic=0x01021994
   # RAMFS_MAGIC
   dont_measure fsmagic=0x858458f6
   # SECURITYFS_MAGIC
   dont_measure fsmagic=0x73636673
   # SELINUX_MAGIC
   dont_measure fsmagic=0xf97cff8c
   # CGROUP_SUPER_MAGIC
   dont_measure fsmagic=0x27e0eb
   # OVERLAYFS_MAGIC
   dont_measure fsmagic=0x794c7630
   # Don't measure log, audit or tmp files
   dont_measure obj_type=var_log_t
   dont_measure obj_type=auditd_log_t
   dont_measure obj_type=tmp_t
   # MEASUREMENTS
   measure func=BPRM_CHECK
   measure func=FILE_MMAP mask=MAY_EXEC
   measure func=MODULE_CHECK uid=0

10. Reboot the system to apply the new IMA policy.

Verification

1. Verify that the agent is running:

   # systemctl status keylime_agent
   ● keylime_agent.service - The Keylime compute agent
        Loaded: loaded (/usr/lib/systemd/system/keylime_agent.service; enabled; preset: disabled)
        Active: active (running) since ...

Procedure

1. On the monitored system where the Keylime agent is configured and running, generate an allowlist from the current state of the system:

   # /usr/share/keylime/scripts/create_allowlist.sh -o <allowlist.txt> -h sha256sum

   Replace <allowlist.txt> with the file name of the allowlist.

   Important

   Use the SHA-256 hash function. SHA-1 is not secure and has been deprecated in RHEL 9. For additional information, see SHA-1 deprecation in Red Hat Enterprise Linux 9.

2. Copy the generated allowlist to the system where the keylime_tenant utility is configured, for example:

   # scp allowlist.txt root@<tenant_._ip>:/root/allowlist.txt

3. Optional: You can define a list of files or directories excluded from Keylime measurements by creating a file on the tenant system and entering the files and directories to exclude. The excludelist accepts Python regular expressions with one regular expression per line. For more information, see Regular expression operations at docs.python.org. For example, to exclude all files in the /tmp/ directory from Keylime measurements, create a /root/excludelist.txt file with the following content:

   /tmp/.*

   Save the excludelist on the tenant system.

4. On the system where the Keylime tenant is configured, provision the agent by using the keylime_tenant utility:

   # keylime_tenant -c add -t <agent_ip> -u <agent_uuid> --allowlist <allowlist.txt> --exclude <excludelist> --cert default

   • Replace <agent_ip> with the agent’s IP address.
   • Replace <agent_uuid> with the agent’s UUID.
   • Replace <allowlist.txt> with the path to the allowlist file.
   • Replace <excludelist> with the path to the excludelist file. The --exclude option is optional; provisioning the agent works even without delivering a file.

   • With the --cert option, the tenant generates and signs a certificate for the agent by using the CA certificates and keys located in the specified directory, or the default /var/lib/keylime/ca/ directory. If the directory contains no CA certificates and keys, the tenant will generate them automatically according to the configuration in the /etc/keylime/ca.conf file and save them to the specified directory. The tenant then sends these keys and certificates to the agent.

     When generating CA certificates or signing agent certificates, you may be prompted for the password to access the CA private key: Please enter the password to decrypt your keystore:.

     If you do not want to use a certificate, use the -f option instead for delivering a file to the agent. Provisioning an agent requires sending any file, even an empty file.

     Note

     Keylime encrypts the file sent to the agent, and decrypts it only if the agent’s system complies with the TPM policy and the IMA allowlist. By default, Keylime decompresses .zip files.

   As an example, with the following command, keylime_tenant provisions a new Keylime agent at 127.0.0.1 with UUID d432fbb3-d2f1-4a97-9ef7-75bd81c00000 and loads an allowlist named allowlist.txt. It also generates a certificate into the default directory and sends it to the agent. Keylime decrypts the file only if the TPM policy configured in /etc/keylime/verifier.conf is satisfied:

   # keylime_tenant -c add -t 127.0.0.1 -u d432fbb3-d2f1-4a97-9ef7-75bd81c00000 -cert default --allowlist allowlist.txt --exclude excludelist.txt

   Note

   You can stop Keylime from monitoring a node by using the # keylime_tenant -c delete -u <agent_uuid> command.

   You can modify the configuration of an already registered agent by using the keylime_tenant -c update command.

Verification

1. Optional: Reboot the monitored system before verification to verify that the settings are persistent.

2. Verify a successful attestation of the agent:

   # keylime_tenant -c cvstatus -u <agent.uuid>
   ...
   {"<agent.uuid>": {"operational_state": "Get Quote"..."attestation_count": 5
   ...

   Replace <agent.uuid> with the agent’s UUID.

   If the value of operational_state is Get Quote and attestation_count is non-zero, the attestation of this agent is successful.

   If the value of operational_state is Invalid Quote or Failed attestation fails, the command displays output similar to the following:

   {"<agent.uuid>": {"operational_state": "Invalid Quote", ... "ima.validation.ima-ng.not_in_allowlist", "attestation_count": 5, "last_received_quote": 1684150329, "last_successful_attestation": 1684150327}}

3. If the attestation fails, display more details in the verifier log:

   # journalctl -u keylime_verifier
   keylime.tpm - INFO - Checking IMA measurement list...
   keylime.ima - WARNING - File not found in allowlist: /root/bad-script.sh
   keylime.ima - ERROR - IMA ERRORS: template-hash 0 fnf 1 hash 0 good 781
   keylime.cloudverifier - WARNING - agent D432FBB3-D2F1-4A97-9EF7-75BD81C00000 failed, stopping polling

Procedure

1. On the monitored system where the Keylime agent is configured and running, install the python3-keylime, which contains create_mb_refstate utility:

   # dnf -y install python3-keylime

2. On the monitored system, generate a policy from the measured boot log of the current state of the system by using the create_mb_refstate script:

   # /usr/share/keylime/scripts/create_mb_refstate /sys/kernel/security/tpm0/binary_bios_measurements <./measured_boot_reference_state.json>

   Replace <./measured_boot_reference_state.json> with the path where the script saves the generated policy.

   Important

   The policy generated with the create_mb_refstate script is based on the current state of the system and is very strict. Any modifications of the system including kernel updates and system updates will change the boot process and the system will fail the attestation.

3. Copy the generated policy to the system where the keylime_tenant utility is configured, for example:

   # scp root@<agent_ip>:/root/measured_boot_reference_state.json /root/measured_boot_reference_state.json

4. On the system where the Keylime tenant is configured, provision the agent by using the keylime_tenant utility:

   # keylime_tenant -c add -t <agent_ip> -u <agent_uuid> --mb_refstate <./measured_boot_reference_state.json>

   • Replace <agent_ip> with the agent’s IP address.
   • Replace <agent_uuid> with the agent’s UUID.
   • Replace <./measured_boot_reference_state.json> with the path to the measured boot policy.

   If you configure measured boot in combination with runtime monitoring, provide all the options from both use cases when entering the keylime_tenant -c add command.

   Note

   You can stop Keylime from monitoring a node by using the # keylime_tenant -c delete -t <agent_ip> -u <agent_uuid> command.

   You can modify the configuration of an already registered agent by using the keylime_tenant -c update command.

Verification

1. Reboot the monitored system and verify a successful attestation of the agent:

   # keylime_tenant -c cvstatus -u <agent_uuid>
   ...
   {"<agent.uuid>": {"operational_state": "Get Quote"..."attestation_count": 5
   ...

   Replace <agent_uuid> with the agent’s UUID.

   If the value of operational_state is Get Quote and attestation_count is non-zero, the attestation of this agent is successful.

   If the value of operational_state is Invalid Quote or Failed attestation fails, the command displays output similar to the following:

   {"<agent.uuid>": {"operational_state": "Invalid Quote", ... "ima.validation.ima-ng.not_in_allowlist", "attestation_count": 5, "last_received_quote": 1684150329, "last_successful_attestation": 1684150327}}

2. If the attestation fails, display more details in the verifier log:

   # journalctl -u keylime_verifier
   {"d432fbb3-d2f1-4a97-9ef7-75bd81c00000": {"operational_state": "Tenant Quote Failed", ... "last_event_id": "measured_boot.invalid_pcr_0", "attestation_count": 0, "last_received_quote": 1684487093, "last_successful_attestation": 0}}

Procedure

1. To install the aide package:

   # dnf install aide

2. To generate an initial database:

   # aide --init

   Note

   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.

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

4. 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: 2018-07-11 12:41:20 +0200 (AIDE 0.16)
   AIDE found differences between database and filesystem!!
   ...
   [trimmed for clarity]

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

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.

3. Mount the device:

   # mount /dev/mapper/nvme_encrypted /mnt/nvme_encrypted

4. 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. Create a new playbook.yml file with the following content:

   - hosts: all
     vars:
       storage_volumes:
         - name: barefs
           type: disk
           disks:
            - sdb
           fs_type: xfs
           fs_label: label-name
           mount_point: /mnt/data
           encryption: true
           encryption_password: your-password
     roles:
      - rhel-system-roles.storage

   You can also add the other encryption parameters such as encryption_key, encryption_cipher, encryption_key_size, and encryption_luks version in the playbook.yml file.

2. Optional: Verify playbook syntax:

   # ansible-playbook --syntax-check playbook.yml

3. Run the playbook on your inventory file:

   # ansible-playbook -i inventory.file /path/to/file/playbook.yml

Verification

1. View the encryption status:

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

2. Verify the created LUKS encrypted volume:

   # cryptsetup luksDump /dev/sdb
   
   Version:       	2
   Epoch:         	6
   Metadata area: 	16384 [bytes]
   Keyslots area: 	33521664 [bytes]
   UUID:          	a4c6be82-7347-4a91-a8ad-9479b72c9426
   Label:         	(no label)
   Subsystem:     	(no subsystem)
   Flags:       	allow-discards
   
   Data segments:
     0: crypt
   	offset: 33554432 [bytes]
   	length: (whole device)
   	cipher: aes-xts-plain64
   	sector: 4096 [bytes]
   [...]

3. View the cryptsetup parameters in the playbook.yml file, which the storage role supports:

   # cat ~/playbook.yml
   
       - hosts: all
         vars:
           storage_volumes:
             - name: foo
               type: disk
               disks:
                - nvme0n1
               fs_type: xfs
               fs_label: label-name
               mount_point: /mnt/data
               encryption: true
               #encryption_password: passwdpasswd
               encryption_key: /home/passwd_key
               encryption_cipher: aes-xts-plain64
               encryption_key_size: 512
               encryption_luks_version: luks2
   
         roles:
          - rhel-system-roles.storage

Procedure

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

   # dnf 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:

   # dnf 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 9.2 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 ramdisk (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:

   # dnf 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:

   # dnf 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:

   # dnf 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:

   # dnf 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:

   # dnf 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/rhel9/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/rhel9/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/rhel9/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. Prepare your playbook containing settings for Tang servers. You can either start from the scratch, or use one of the example playbooks from the /usr/share/ansible/roles/rhel-system-roles.nbde_server/examples/ directory.

   # cp /usr/share/ansible/roles/rhel-system-roles.nbde_server/examples/simple_deploy.yml ./my-tang-playbook.yml

2. Edit the playbook in a text editor of your choice, for example:

   # vi my-tang-playbook.yml

3. Add the required parameters. The following example playbook ensures deploying of your Tang server and a key rotation:

   ---
   - hosts: all
   
     vars:
       nbde_server_rotate_keys: yes
       nbde_server_manage_firewall: true
       nbde_server_manage_selinux: true
   
     roles:
       - rhel-system-roles.nbde_server

   Note

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

4. Apply the finished playbook:

   # ansible-playbook -i inventory-file my-tang-playbook.yml

   Where: * inventory-file is the inventory file. * logging-playbook.yml is the playbook you use.

Procedure

1. Prepare your playbook containing settings for Clevis clients. You can either start from the scratch, or use one of the example playbooks from the /usr/share/ansible/roles/rhel-system-roles.nbde_client/examples/ directory.

   # cp /usr/share/ansible/roles/rhel-system-roles.nbde_client/examples/high_availability.yml ./my-clevis-playbook.yml

2. Edit the playbook in a text editor of your choice, for example:

   # vi my-clevis-playbook.yml

3. Add the required parameters. The following example playbook configures Clevis clients for automated unlocking of two LUKS-encrypted volumes by when at least one of two Tang servers is available:

   ---
   - hosts: all
   
     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
   
     roles:
       - rhel-system-roles.nbde_client

4. Apply the finished playbook:

   # ansible-playbook -i host1,host2,host3 my-clevis-playbook.yml

File-system rules examples

1. To define a rule that logs all write access to, and every attribute change of, the /etc/passwd file:

   # auditctl -w /etc/passwd -p wa -k passwd_changes

2. To define a rule that logs all write access to, and every attribute change of, all the files in the /etc/selinux/ directory:

   # auditctl -w /etc/selinux/ -p wa -k selinux_changes

System-call rules examples

1. To define a rule that creates a log entry every time the adjtimex or settimeofday system calls are used by a program, and the system uses the 64-bit architecture:

   # auditctl -a always,exit -F arch=b64 -S adjtimex -S settimeofday -k time_change

2. To define a rule that creates a log entry every time a file is deleted or renamed by a system user whose ID is 1000 or larger:

   # auditctl -a always,exit -S unlink -S unlinkat -S rename -S renameat -F auid>=1000 -F auid!=4294967295 -k delete

   Note that the -F auid!=4294967295 option is used to exclude users whose login UID is not set.

Procedure

1. Copy the /usr/lib/systemd/system/auditd.service file to the /etc/systemd/system/ directory:

   # cp -f /usr/lib/systemd/system/auditd.service /etc/systemd/system/

2. Edit the /etc/systemd/system/auditd.service file in a text editor of your choice, for example:

   # vi /etc/systemd/system/auditd.service

3. Comment out the line containing augenrules, and uncomment the line containing the auditctl -R command:

   #ExecStartPost=-/sbin/augenrules --load
   ExecStartPost=-/sbin/auditctl -R /etc/audit/audit.rules

4. Reload the systemd daemon to fetch changes in the auditd.service file:

   # systemctl daemon-reload

5. Restart the auditd service:

   # service auditd restart

Procedure

1. Copy the pre-configured rule file 44-installers.rules from the /usr/share/audit/sample-rules/ directory to the /etc/audit/rules.d/ directory:

   # cp /usr/share/audit/sample-rules/44-installers.rules /etc/audit/rules.d/

2. Load the audit rules:

   # augenrules --load

Verification

1. List the loaded rules:

   # auditctl -l
   -p x-w /usr/bin/dnf-3 -k software-installer
   -p x-w /usr/bin/yum -k software-installer
   -p x-w /usr/bin/pip -k software-installer
   -p x-w /usr/bin/npm -k software-installer
   -p x-w /usr/bin/cpan -k software-installer
   -p x-w /usr/bin/gem -k software-installer
   -p x-w /usr/bin/luarocks -k software-installer

2. Perform an installation, for example:

   # dnf reinstall -y vim-enhanced

3. Search the Audit log for recent installation events, for example:

   # ausearch -ts recent -k software-installer
   ––––
   time->Thu Dec 16 10:33:46 2021
   type=PROCTITLE msg=audit(1639668826.074:298): proctitle=2F7573722F6C6962657865632F706C6174666F726D2D707974686F6E002F7573722F62696E2F646E66007265696E7374616C6C002D790076696D2D656E68616E636564
   type=PATH msg=audit(1639668826.074:298): item=2 name="/lib64/ld-linux-x86-64.so.2" inode=10092 dev=fd:01 mode=0100755 ouid=0 ogid=0 rdev=00:00 obj=system_u:object_r:ld_so_t:s0 nametype=NORMAL cap_fp=0 cap_fi=0 cap_fe=0 cap_fver=0 cap_frootid=0
   type=PATH msg=audit(1639668826.074:298): item=1 name="/usr/libexec/platform-python" inode=4618433 dev=fd:01 mode=0100755 ouid=0 ogid=0 rdev=00:00 obj=system_u:object_r:bin_t:s0 nametype=NORMAL cap_fp=0 cap_fi=0 cap_fe=0 cap_fver=0 cap_frootid=0
   type=PATH msg=audit(1639668826.074:298): item=0 name="/usr/bin/dnf" inode=6886099 dev=fd:01 mode=0100755 ouid=0 ogid=0 rdev=00:00 obj=system_u:object_r:rpm_exec_t:s0 nametype=NORMAL cap_fp=0 cap_fi=0 cap_fe=0 cap_fver=0 cap_frootid=0
   type=CWD msg=audit(1639668826.074:298): cwd="/root"
   type=EXECVE msg=audit(1639668826.074:298): argc=5 a0="/usr/libexec/platform-python" a1="/usr/bin/dnf" a2="reinstall" a3="-y" a4="vim-enhanced"
   type=SYSCALL msg=audit(1639668826.074:298): arch=c000003e syscall=59 success=yes exit=0 a0=55c437f22b20 a1=55c437f2c9d0 a2=55c437f2aeb0 a3=8 items=3 ppid=5256 pid=5375 auid=0 uid=0 gid=0 euid=0 suid=0 fsuid=0 egid=0 sgid=0 fsgid=0 tty=pts0 ses=3 comm="dnf" exe="/usr/libexec/platform-python3.6" subj=unconfined_u:unconfined_r:unconfined_t:s0-s0:c0.c1023 key="software-installer"

Procedure

1. Install the fapolicyd package:

   # dnf install fapolicyd

2. Enable and start the fapolicyd service:

   # systemctl enable --now fapolicyd

Verification

1. Verify that the fapolicyd service is running correctly:

   # systemctl status fapolicyd
   ● fapolicyd.service - File Access Policy Daemon
      Loaded: loaded (/usr/lib/systemd/system/fapolicyd.service; enabled; vendor p>
      Active: active (running) since Tue 2019-10-15 18:02:35 CEST; 55s ago
     Process: 8818 ExecStart=/usr/sbin/fapolicyd (code=exited, status=0/SUCCESS)
    Main PID: 8819 (fapolicyd)
       Tasks: 4 (limit: 11500)
      Memory: 78.2M
      CGroup: /system.slice/fapolicyd.service
              └─8819 /usr/sbin/fapolicyd
   
   Oct 15 18:02:35 localhost.localdomain systemd[1]: Starting File Access Policy D>
   Oct 15 18:02:35 localhost.localdomain fapolicyd[8819]: Initialization of the da>
   Oct 15 18:02:35 localhost.localdomain fapolicyd[8819]: Reading RPMDB into memory
   Oct 15 18:02:35 localhost.localdomain systemd[1]: Started File Access Policy Da>
   Oct 15 18:02:36 localhost.localdomain fapolicyd[8819]: Creating database

2. Log in as a user without root privileges, and check that fapolicyd is working, for example:

   $ cp /bin/ls /tmp
   $ /tmp/ls
   bash: /tmp/ls: Operation not permitted

Procedure

1. Copy your custom binary to the required directory, for example:

   $ cp /bin/ls /tmp
   $ /tmp/ls
   bash: /tmp/ls: Operation not permitted

2. Mark your custom binary as trusted, and store the corresponding entry to the myapp file in /etc/fapolicyd/trust.d/:

   # fapolicyd-cli --file add /tmp/ls --trust-file myapp

   • If you skip the --trust-file option, then the previous command adds the corresponding line to /etc/fapolicyd/fapolicyd.trust.
   • To mark all existing files in a directory as trusted, provide the directory path as an argument of the --file option, for example: fapolicyd-cli --file add /tmp/my_bin_dir/ --trust-file myapp.

3. Update the fapolicyd database:

   # fapolicyd-cli --update