add initial design overview and threat model

docs/design.rst

@@ -0,0 +1,12 @@
+=================
+Design of Keylime
+=================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   design/overview.rst
+   design/threat_model.rst
+
+

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

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.

docs/index.rst

@@ -26,6 +26,7 @@ or develop services against Keylime's Rest API(s).
 
    installation
    user_guide
+   design
    rest_apis
    developers
    security