============
Threat Model
============

Keylime was originally developed with the intention of using it in combination with hypervisors to protect the VMs
against by using the vTPM support in Xen. vTPM support for TPM2.0 was never implemented into Keylime and swtpm+libvirt
never supported it, so this model no longer fits. Keylime is commonly used either on bare metal hardware or in VMs where
the TPM is emulated but from VM side treated the same as a hardware TPM. Therefore the common threat model is defined on
the latter use case.


.. note::
    The term vTPM can be confusing because it originally described the deep quote feature in Xen which Keylime used for
    TPM 1.2. Now it commonly refers to a software implementation of a TPM (e.g. swtpm) or the Virtual TPM Proxy Driver
    in the Linux kernel.

From Keylime's perspective the core hardware like CPU, memory, motherboard is trusted, because it does not provide
mechanisms to detect tampering with the hardware itself.
Keylime chains its root of trust into the TPM therefore the TPM is deemed in general trustworthy. This trust is verified
using the EK or EK certificate.

The goal of Keylime is to attest the state of a running system. For this to work the entire boot chain has to be
verified. The UEFI with Secure Boot enabled firmware and CRTM are generally trusted because it provides the UEFI event
log and the API for other EFI applications to use the TPM. All the other applications in the boot chain are either
measured by the firmware or the application that loads them (e.g. GRUB2 loads the kernel). The threat model does not
require to trust arbitrary EFI applications during the boot process because it can be verified after boot what was
executed.


The threat model includes that an adversary has full control over the network and can either sent rouge messages,
drop or modify them. Also the Keylime agent and running operating system itself is not deemed trustworthy by default.
Only after the successful initial attestation the system is deemed trustworthy, but still can leave the trusted state
at any moment and is therefore continuously attested.


Types of Attacks to detect
--------------------------
Keylime tries to detect the following attacks.

TPM Quote Manipulation
""""""""""""""""""""""
Because the TPM is the root-of-trust for Keylime, it ensures that the quote is valid.
This is vital for all the other attestation steps because the quote is used to validate the data.

Keylime ensures this through three steps:

  * EK validation: The tenant allows Keylime to verify the EK certificate against the CAs of hardware manufacturers
    or add custom validation steps. This is done to ensure that the EK belongs to an actual hardware TPM or a trusted
    software TPM.
  * AK enrollment: Using the TPM commands `MakeCredential`, `ActivateCredential` and enforcing certain key properties
    (restricted, user with auth, sign encrypt, fixed TPM, fixed parent and sensitive data origin)
    Keylime ensures that the used AK belongs to the provided EK and has the right properties for signing quotes.
  * Quote validation: Each quote generated by the TPM is verified with the AK provided during agent registration.
    The verifier provides a fresh nonce that is included in the quote to prohibit replay attacks.


Modification of the boot process
""""""""""""""""""""""""""""""""
Checking the security of the running system does only make sense if it can be ensured that the system was correctly
booted. Therefore Keylime provides two ways to allow users to verify the entire boot chain up to the running system:
static PCR value checks (:doc:`../user_guide/user_selected_pcr_monitoring`) and the measured boot policy engine
(:doc:`../user_guide/use_measured_boot`).


Runtime file and system integrity
"""""""""""""""""""""""""""""""""
Keylime can attest the state of a Linux system and the files using the Linux Integrity Measurement Architecture (IMA).
Therefore Keylime can be used to remotely check for attacks that IMA detects.