diff --git a/docs/design.rst b/docs/design.rst new file mode 100644 index 0000000..84b5c32 --- /dev/null +++ b/docs/design.rst @@ -0,0 +1,12 @@ +================= +Design of Keylime +================= + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + design/overview.rst + design/threat_model.rst + + diff --git a/docs/design/overview.rst b/docs/design/overview.rst new file mode 100644 index 0000000..25b41fd --- /dev/null +++ b/docs/design/overview.rst @@ -0,0 +1,86 @@ +=================== +Overview of Keylime +=================== + +Keylime mainly consists of an agent, two server components (verifier and registrar) and a commandline tool the tenant. + +Agent +----- + +The agent is a service that runs on the operating system that should be attested. +It communicates with the TPM to enroll the AK and to generate quotes and +collects the necessary data like the UEFI and IMA event logs to make state attestation +possible. + +The agent provides an interface to provision the device further once it was attested +successfully for the first time using the secure payload mechanism. +For more details see: :doc:`../user_guide/secure_payload`. + +It is possible for the agent to listen to revocation events that are sent by the verifier +if an agent attestation failed. This is useful for environments where attested systems +directly communicate with each other and require that the other systems are trusted. +In this case a revocation message might change local policies so that the compromised +system cannot access any resources from other systems. + +Registrar +--------- +The agent registers itself in the registrar. +The registrar manages the agent enrollment process which includes +getting an UUID for the agent, collecting the `EK`:sub:`pub`, EK certificate and `AK`:sub:`pub` from an agent +and verifying that the `AK` belongs to the `EK` (using `MakeCredential` and `ActivateCredential`). + + +Once an agent has been registered in the registrar, it is ready to be enrolled for attestation. +The tenant can use the EK certificate to verify to verify the trustworthiness of the TPM. +Both the tenant and verifier + +.. note:: + If `EK` or `AK` are mentioned outside of internal TPM signing operations, it usually + references the `EK`:sub:`pub` or `AK`:sub:`pub` because it should not be possible + extract the private keys out of the TPM. + +.. note:: + The Keylime agent currently generates a `AK` on every startup and sends the EK and + EK certificate. This is done to keep then design simple by not requiring a third + party to verify the EK. + The EK (and EK certificate) is required to verify the authenticity of the AK once + and Keylime does not require a new AK but currently registration only with an AK + is not enabled because the agent does not implement persisting the AK. + +Verifier +-------- +The verifier implements the actual attestation of an agent and sends revocation messages if an agent leaves the trusted +state. + +Once an agent is registered for attestation (using the tenant or the API directly) the verifier continuously pulls +the required attestation data from the agent. This can include: a quote over the PCRs, the PCR values, NK public key, +IMA log and UEFI event log. After that the quote is validated additional validation of the data can be configured. + +Static PCR values +""""""""""""""""" +The `tpm_policy` allows for simple checking of PCR values against a known good allowlist. In most cases this is only +useful when the boot chain does not change often, there is a way to retrieve the values beforehand +and the UEFI event log is unavailable. +More information can be found in :doc:`../user_guide/user_selected_pcr_monitoring`. + +Measured Boot using the UEFI Event Log +"""""""""""""""""""""""""""""""""""""" +On larger deployments it is not feasible to collect golden values for the PCR values used for measured boot. To make +attestation still possible Keylime includes a policy engine for validating the UEFI event log. This is the preferred +method because static PCR values are fragile because they change if something in the boot chain is updated (firmware, +Shim, GRUB, Linux kernel, initrd, ...). More information can be found in :doc:`../user_guide/use_measured_boot`. + +IMA validation +"""""""""""""" +Keylime allows to verify files measured by IMA against either a provided allowlist or a signature. +This makes it for example easy to attest all files that were executed by root. +More information can be found in :doc:`../user_guide/runtime_ima`. + + +Tenant +------ +The tenant is a commandline management tool shipped by Keylime to manage agents. +This includes adding or removing the agent from attestation, validation of the EK certificate against a cert store and +getting the status of an agent. It also provides the necessary tools for the payload mechanism and revocation actions. + +For all the features of the tenant see the output of ``keylime_tenant --help``. \ No newline at end of file diff --git a/docs/design/threat_model.rst b/docs/design/threat_model.rst new file mode 100644 index 0000000..088d8f1 --- /dev/null +++ b/docs/design/threat_model.rst @@ -0,0 +1,68 @@ +============ +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. \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 7c4c59b..5df0069 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -26,6 +26,7 @@ or develop services against Keylime's Rest API(s). installation user_guide + design rest_apis developers security