Applies to SUSE Linux Enterprise Micro 5.3

2 Remote attestation using Keylime #

This chapter focuses on the remote attestation of SLE Micro using the Keylime agent.

With the growing demand on securing devices against unauthorized changes, the use of the security mechanism called remote attestation (RA) has been experiencing significant growth. Using RA, a host (client) can authenticate its boot chain status and running software on a remote host (verifier). Remote attestation is usually combined with public-key encryption (by using TPM2), thus the sent information can only be read by the services that requested the attestation, and the validity of the data can be verified.

Throughout this document, the following terms are used:

Terminology #

Attestation key (AK): is a data signing key that proves that the data comes from a real TPM and has not been tampered with.
Core root of trust for measurement: is a starting point of the boot process that cannot be altered and calculates the first hash of the layer above.
Endorsement key (EK): is an encryption key that is permanently embedded in the TPM when it is manufactured. The public part of the key is used to recognize a genuine TPM.
Integrity management architecture (IMA): the kernel integrity subsystem that provides a means of detecting malicious changes to files.
Measured boot: in this method, each component in the booting sequence calculates a hash of the next one before delegating the execution of the next component. The hash extends one or several PCRs of the TPM. An event is created with the information about where the measurement took place and what was measured. Such events are collected in an event log, and, along with the extended PCR values, the events can be compared with the expected values representing a healthy system.
Platform Configuration Register (PCR): is a memory location in TPM that, for example, stores hashes of booting layers. PCR can be updated only by using the non-reversible operation—extend. A signed list of current PCR values can be obtained by the quote command on TPM, and this quote can be verified by a third party during the attestation process.
Secure boot: each step of the booting process checks a cryptographic signature on the executable of the next step before launching it.
Trusted Platform Module (TPM): is a self-contained security cryptographic processor present in the system as hardware or implemented in the firmware that serves as a root of trust. TPM provides a PCR for storing the hashes of booting layers. A typical TPM provides several functions, like a random number generator, counters, or a local clock. It also stores 24 PCRs, grouped by banks per each supported cryptographic hash function (SHA1, SHA256, SHA384, or SHA512).

Usually, by default, TPM usage is disabled. Therefore, the measured boot does not take place. To enable the remote attestation, enable TPM in the EFI/BIOS menu.

2.1 About Keylime #

Keylime is a remote attestation solution that enables you to monitor the health of remote nodes using a TPM as a root of trust for measurement. With Keylime, you can perform several tasks like validation of the PCRs extended during the measured boot, analysis and assertions of the event log, assertion of the value of any PCR in the remote system, and also monitoring the validity of open or executed files.

Keylime also provides a framework for delivering encrypted data to verified nodes. This data is the so-called payload. The framework can also execute custom scripts that are triggered when a machine fails the attested measurements.

Keylime consists of an agent, a verifier, a registrar, and a command-line tool (tenant). Agents are on those systems that need to be attested. The verifier and registrar are on remote systems that perform the registration and attestation of agents. Keep in mind that only the agent role is available on SLE Micro. For details about each component, refer to the following sections.

2.1.1 Keylime agent #

The agent is a service that runs on the system that needs to be attested. The agent sends the event log, IMA hashes, and information about the measured boot to the verifier, using the local TPM as a certifier of the data validity.

When a new agent is started, the agent needs to register itself in the registrar first. To do so, the agent needs a TLS certificate to establish the connection. The TLS certificate is generated by the registrar, but it needs to be installed manually to the agent. After the registration, the agent sends its attestation key and the public part of the endorsement key to the registrar. The registrar responds to the agent with a challenge in a process called credential activation, which will validate the TPM of the agent. Once the agent has been registered, it is ready to be enrolled for attestation.

2.1.2 Keylime registrar #

The registrar is used to register agents that should be attested. The registrar collects the agent's attestation key, the public part of the endorsement key and the endorsement key certification, and verifies that the agent attestation key belongs to the endorsement key.

2.1.3 Keylime verifier #

The verifier performs the actual attestation of agents and continuously pulls the required attestation data from agents (amongst others, the PCR values, IMA logs, and UEFI event logs).

2.2 Setting up the verifier and registrar #

Before you start installing and registering agents, prepare the verifier and the registrar on remote hosts as described in the following procedure.

Check the content of configuration files in /usr/etc/keylime/*.conf. The defaults are usually sufficient without any changes, but if you need to adjust the configuration, add the changes to either /etc/keylime/verifier.conf.d/ or /etc/keylime/registrar.conf.d/. Set the ownership to keylime:tss and change the permissions as follows (for the verifier node):
```
# chown -R keylime:tss /etc/keylime/verifier.conf.d/

# chmod -R 600 /etc/keylime/verifier.conf.d/
```
Start and enable the verifier service:
```
# systemctl enable --now keylime_verifier.service
```
Starting the service generates certificates that are further required by the registrar.
If the previous command completes successfully, you can start and enable the registrar service:
```
# systemctl enable --now keylime_registrar.service
```

2.3 Installing the Keylime agent #

The Keylime agent is not present on SLE Micro by default, you need to install it manually. To install the agent, proceed as follows:

Install the rust-keylime package as follows:

# transactional-update pkg in rust-keylime

Reboot your system.
Adjust the default agent's configuration.
1. Create a directory to store a new configuration file for your changes in /etc/keylime/agent.conf.d/. The default configuration is stored in /usr/etc/keylime/agent.conf, but we do not recommend editing this file, because it might get overwritten with next system updates.
```
# mkdir -p /etc/keylime/agent.conf.d
```
2. Create a new file /etc/keylime/agent.conf.d/agent.conf:
```
# cat << EOF > /etc/keylime/agent.conf.d/agent.conf
 [agent]
 
 uuid = "d111ec46-34d8-41af-ad56-d560bc97b2e8"
 registrar_ip = "<REMOTE_IP>"
 revocation_notification_ip = "<REMOTE_IP>"
 EOF
```
  where:
  - uuid is generated each time the agent is run. However, you can define a specific value by this option.
  - <REMOTE_IP> is an IP address of the registrar.
  - <REMOTE_IP> is an IP address of the verifier.
3. Change the owner of the /etc/keylime/ directory to keylime:tss:
```
# chown -R keylime:tss /etc/keylime
```
4. Change permissions on the /etc/keylime/ directory:
```
# chmod -R 600 /etc/keylime
```
Copy the certificates generated by the CA to the agent node. On the agent node, run:
1. Prepare a directory for the certificate:
```
# mkdir -p /var/lib/keylime/cv_ca
```
2. Copy the certificate to the agent:
```
# scp CERT_SERVER_ADDRESS:/var/lib/keylime/cv_ca/cacert.crt /var/lib/keylime/cv_ca
```
3. Change the owner of the certificate to keylime:
```
# chown -R keylime:tss /var/lib/keylime/cv_ca
```

Start and enable the keylime_agent.service:

# systemctl enable --now keylime_agent.service

2.4 Registering agents #

Note: SLE Micro does not provide the tenant, registrar or verifier

SLE Micro provides only the Keylime agent capability, therefore, the tasks performed in this chapter cannot be performed from your SLE Micro.

You can register a new agent either by using the CLI tenant or by editing the configuration of the verifier. Using the tenant on the verifier host, run the following:

# keylime_tenant -v 127.0.0.1 \
                -t AGENT \
                -u UUID \
                --cert default \
                -c add
                [--include PATH_TO_ZIP_FILE]

Where:

AGENT is an IP address of the agent to be registered.
UUID is the agent's UUID.
the file passed by the include option is used to deliver secret payload data to the agent. For details, refer to Section 2.5, “Secure payloads”.

You can list registered agents by using the reglist command on the verifier host as follows:

# keylime_tenant -v 127.0.0.1 \
                --cert default \
                -c reglist

To remove a registered agent, specify the agent using the -t and -u options and the -c delete command as follows:

# keylime_tenant -v 127.0.0.1 \
              -t AGENT \
              -u UUID \
              -c delete

2.5 Secure payloads #

A secure payload enables you to deliver encrypted data to healthy agents. Typically, these payloads are used to provide keys, passwords, certificates, configurations, or scripts that are further used by the agent.

The secure payload is delivered to the agent in a zip file that must contain a shell script—autorun.sh. The script will be executed only if the agent has been properly registered and verified. To deliver the zip file, use the --include option of the keylime_tenant command.

The script autorun.sh contains steps that will enable the use of passwords, certificates and so on. For example, the script can create a directory structure and copy SSH keys there:

#!/bin/bash
 
 mkdir -p /root/.ssh/
 cp id_rsa* /root/.ssh/
 chmod 600 /root/.ssh/id_rsa*
 cp /root/.ssh/id_rsa.pub /root/.ssh/authorized_keys

In this case, do not forget to include the SSH keys in the zip file.

2.6 Enabling IMA tracking #

When using IMA, the kernel calculates a hash of accessed files. The hash is then used to extend the PCR 10 in the TPM and also log a list of accessed files. The verifier can request a signed quote to the agent for PCR 10 to get the logs of all accessed files including the file hashes. Verifiers then compare the accessed files with a local allowlist of approved files. If any of the hashes are not recognized, the system is considered unsafe, and a revocation event is triggered.

For a high-level overview of IMA/EVM, refer to IMA/EVM introduction.

Before Keylime can collect information, IMA/EVM needs to be enabled. To enable the process, boot a kernel of the agent with the parameters: ima_appraise=log and ima_policy=tcb. To use the boot parameters on boot, proceed as follows:

Update the GRUB_CMDLINE_LINUX_DEFAULT option with the parameters in /etc/default/grub:
```
GRUB_CMDLINE_LINUX_DEFAULT="ima_appraise=log ima_policy=tcb"
```
Regenerate grub.cfg by running:
```
# transactional-update grub.cfg
```
Reboot your system.

The procedure above uses the default kernel IMA policy, but we recommend creating a new policy to avoid monitoring too many files and therefore creating long logs. For details, refer to the Keylime documentation.

To indicate the expected hashes, use the --allowlistoption of the keylime_tenant command when registering the agent. To view the excluded or ignored files, use the --exclude option of the keylime_tenant command:

# keylime_tenant --allowlist
    -v 127.0.0.1 \
    -u UUID