Add keylime-docs into main keylime repo

Author: mpeters

docs/.readthedocs.yml

@@ -0,0 +1,7 @@
+version: 2
+formats: all
+sphinx:
+  configuration: conf.py
+python:
+   install:
+      - requirements: requirements.txt

docs/Makefile

@@ -0,0 +1,19 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/README.md

@@ -0,0 +1,9 @@
+# keylime-docs
+
+[![Documentation Status](https://readthedocs.org/projects/keylime-docs/badge/?version=latest)](https://keylime-docs.readthedocs.io/en/latest/?badge=latest)
+
+All Keylime documentation is formatted in [reStructuredText](https://en.wikipedia.org/wiki/ReStructuredText)
+
+The documentation project is built using [sphinx](http://www.sphinx-doc.org)
+
+Documentation is hosted on [readthedocs](https://readthedocs.org/)

docs/_config.yml

@@ -0,0 +1 @@
+theme: jekyll-theme-tactile

docs/conf.py

@@ -0,0 +1,186 @@
+# -*- coding: utf-8 -*-
+#
+# Configuration file for the Sphinx documentation builder.
+#
+# This file does only contain a selection of the most common options. For a
+# full list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'Keylime Documentation'
+copyright = '2022, Keylime Developers'
+author = 'Keylime Developers'
+
+# The short X.Y version
+version = ''
+# The full version, including alpha/beta/rc tags
+release = '6.4.1'
+
+
+# -- General configuration ---------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.viewcode',
+    'sphinx.ext.autosectionlabel',
+    'sphinx.ext.autodoc',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.githubpages',
+    'sphinxcontrib.httpdomain',
+    'sphinx_tabs.tabs',
+    'sphinx-prompt',
+    'recommonmark',
+    'notfound.extension',
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = None
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+#html_theme = 'alabaster'
+html_theme = 'sphinx_rtd_theme'
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+# html_theme_options = {}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# The default sidebars (for documents that don't match any pattern) are
+# defined by theme itself.  Builtin themes are using these templates by
+# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
+# 'searchbox.html']``.
+#
+# html_sidebars = {}
+
+
+# -- Options for HTMLHelp output ---------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'KeylimeDocumentationdoc'
+
+
+# -- Options for LaTeX output ------------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'KeylimeDocumentation.tex', 'Keylime Documentation Documentation',
+     'Keylime Developers', 'manual'),
+]
+
+
+# -- Options for manual page output ------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'keylimedocumentation', 'Keylime Documentation Documentation',
+     [author], 1)
+]
+
+
+# -- Options for Texinfo output ----------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'KeylimeDocumentation', 'Keylime Documentation Documentation',
+     author, 'KeylimeDocumentation', 'One line description of project.',
+     'Miscellaneous'),
+]
+
+
+# -- Options for Epub output -------------------------------------------------
+
+# Bibliographic Dublin Core info.
+epub_title = project
+
+# The unique identifier of the text. This can be a ISBN number
+# or the project homepage.
+#
+# epub_identifier = ''
+
+# A unique identification for the text.
+#
+# epub_uid = ''
+
+# A list of files that should not be packed into the epub file.
+epub_exclude_files = ['search.html']
+
+
+# -- Extension configuration -------------------------------------------------

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.