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 playbook file, for example ~/playbook.yml, with the following content:

   ---
   - name: Configure crypto policies
     hosts: managed-node-01.example.com
     tasks:
       - name: Configure crypto policies
         ansible.builtin.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 setting causes the system to reboot after the System Role changes the cryptographic policy.

2. Validate the playbook syntax:

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

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

3. Run the playbook:

   $ ansible-playbook ~/playbook.yml

Verification

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

   ---
   - name: Verification
     hosts: managed-node-01.example.com
     tasks:
       - name: Verify active crypto policy
         ansible.builtin.include_role:
           name: rhel-system-roles.crypto_policies
       - debug:
           var: crypto_policies_active

2. Validate the playbook syntax:

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

3. Run the playbook:

   $ ansible-playbook ~/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 verifier by creating 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 option.

3. Optional: Configure the verifier’s database for the list of agents. The default configuration uses an SQLite database in the verifier’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 provide 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 by creating 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:

     [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. Create a playbook that defines the required role:

   1. Create a new YAML file and open it in a text editor, for example:

      # vi keylime-playbook.yml

   2. Insert the following content:

      ---
      - name: Manage keylime servers
        hosts: all
        vars:
          keylime_server_verifier_ip: "{{ ansible_host }}"
          keylime_server_registrar_ip: "{{ ansible_host }}"
          keylime_server_verifier_tls_dir: <ver_tls_directory>
          keylime_server_verifier_server_cert: <ver_server_certfile>
          keylime_server_verifier_server_key: <ver_server_key>
          keylime_server_verifier_server_key_passphrase: <ver_server_key_passphrase>
          keylime_server_verifier_trusted_client_ca: <ver_trusted_client_ca_list>
          keylime_server_verifier_client_cert: <ver_client_certfile>
          keylime_server_verifier_client_key: <ver_client_key>
          keylime_server_verifier_client_key_passphrase: <ver_client_key_passphrase>
          keylime_server_verifier_trusted_server_ca: <ver_trusted_server_ca_list>
          keylime_server_registrar_tls_dir: <reg_tls_directory>
          keylime_server_registrar_server_cert: <reg_server_certfile>
          keylime_server_registrar_server_key: <reg_server_key>
          keylime_server_registrar_server_key_passphrase: <reg_server_key_passphrase>
          keylime_server_registrar_trusted_client_ca: <reg_trusted_client_ca_list>
        roles:
          - rhel-system-roles.keylime_server

      You can find out more about the variables in Variables for the keylime_server RHEL System Role.

2. Run the playbook:

   $ ansible-playbook <keylime-playbook.yml>

Verification

1. Check that the keylime_verifier service is active and running on the managed host:

   # systemctl status keylime_verifier
   ● keylime_verifier.service - The Keylime verifier
        Loaded: loaded (/usr/lib/systemd/system/keylime_verifier.service; disabled; vendor preset: disabled)
        Active: active (running) since Wed 2022-11-09 10:10:08 EST; 1min 45s ago

2. Check that the keylime_registrar service is active and running:

   # systemctl status keylime_registrar
   ● keylime_registrar.service - The Keylime registrar service
        Loaded: loaded (/usr/lib/systemd/system/keylime_registrar.service; disabled; vendor preset: disabled)
        Active: active (running) since Wed 2022-11-09 10:10:17 EST; 1min 42s ago
   ...

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.
   • 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 = ['</path/to/ca/cert>']

      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:

   # 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

   The Keylime agent configuration uses the TOML format, which is different from the INI format used for configuration of the other components. Therefore, enter values in valid TOML syntax, for example, paths in single quotation marks and arrays of multiple paths in square brackets.

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

   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>'
   trusted_client_ca = '[</path/to/ca/cert3>, </path/to/ca/cert4>]'

   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
   # Do not 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. See Regular expression operations at docs.python.org for the complete list of special characters. For example, to exclude all files in the /tmp/ directory and some subdirectories of the /var/ directory from Keylime measurements, create a /root/<excludelist.txt> file with the following content:

   /var/cache/.*
   /var/lock/.*
   /var/log/.*
   /var/run/.*
   /var/spool/.*
   /var/tmp/.*
   /tmp/.*

   Save the excludelist on the tenant system.

4. Combine the allowlist and excludelist into the Keylime runtime policy:

   # keylime_create_policy -a <allowlist.txt> -e <excludelist.txt> -o <policy.json>

5. 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> --runtime-policy <policy.json> --cert default

   • Replace <agent_ip> with the agent’s IP address.
   • Replace <agent_uuid> with the agent’s UUID.
   • Replace <policy.json> with the path to the Keylime runtime policy 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 a runtime policy policy.json. It also generates a certificate in the default directory and sends the certificate file 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 --runtime-policy policy.json

   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 package, which contains the create_mb_refstate script:

   # 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>:<./measured_boot_reference_state.json> <./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. Install the aide package:

   # dnf install aide

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

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 playbook file, for example ~/playbook.yml, with the following content:

   ---
   - name: Create and configure a volume encrypted with LUKS
     hosts: managed-node-01.example.com
     roles:
       - rhel-system-roles.storage
     vars:
       storage_volumes:
         - name: barefs
           type: disk
           disks:
            - sdb
           fs_type: xfs
           fs_label: label-name
           mount_point: /mnt/data
           encryption: true
           encryption_password: <password>

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

2. Validate the playbook syntax:

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

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

3. Run the playbook:

   $ ansible-playbook ~/playbook.yml

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

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 RAM disk (initrd). For non-root file systems, the web console now enables the remote-cryptsetup.target and clevis-luks-akspass.path systemd units, installs the clevis-systemd package, and adds the _netdev parameter to the fstab and crypttab configuration files.

Verification

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

   

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

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

Procedure

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

   # 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. Create a playbook file, for example ~/playbook.yml, with the following content:

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

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

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

2. Validate the playbook syntax:

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

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

3. Run the playbook:

   $ ansible-playbook ~/playbook.yml

Procedure

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

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

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

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

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

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

2. Validate the playbook syntax:

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

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

3. Run the playbook:

   $ ansible-playbook ~/playbook.yml

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"