├── docs ├── _config.yml ├── images │ └── whitelist_ui.png ├── user_guide │ ├── revocation.rst │ ├── encrypted_payload.rst │ ├── user_selected_pcr_monitoring.rst │ └── runtime_ima.rst ├── user_guide.rst ├── security.rst ├── Makefile ├── index.rst ├── rest_apis.rst ├── conf.py ├── developers.rst └── installation.rst ├── requirements.txt ├── setup.py ├── .readthedocs.yml ├── requirements └── pip.txt ├── README.md └── setup.cfg /docs/_config.yml: -------------------------------------------------------------------------------- 1 | theme: jekyll-theme-tactile 2 | -------------------------------------------------------------------------------- /requirements.txt: -------------------------------------------------------------------------------- 1 | -r requirements/pip.txt 2 | -------------------------------------------------------------------------------- /setup.py: -------------------------------------------------------------------------------- 1 | from setuptools import setup 2 | 3 | 4 | # Configuration is in setup.cfg 5 | setup() 6 | -------------------------------------------------------------------------------- /docs/images/whitelist_ui.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/font/keylime-docs/master/docs/images/whitelist_ui.png -------------------------------------------------------------------------------- /.readthedocs.yml: -------------------------------------------------------------------------------- 1 | version: 2 2 | formats: all 3 | sphinx: 4 | configuration: docs/conf.py 5 | python: 6 | install: 7 | - requirements: requirements/pip.txt 8 | -------------------------------------------------------------------------------- /requirements/pip.txt: -------------------------------------------------------------------------------- 1 | sphinxcontrib-httpdomain==1.7.0 2 | sphinx-tabs 3 | sphinx-prompt==1.0.0 4 | sphinx_rtd_theme>=0.3.1 5 | recommonmark==0.5.0 6 | sphinx-notfound-page==0.2.1 7 | commonmark==0.8.1 8 | -------------------------------------------------------------------------------- /docs/user_guide/revocation.rst: -------------------------------------------------------------------------------- 1 | Agent Revocation 2 | ================ 3 | 4 | .. warning:: 5 | This page is still under development and not complete. It will be so until 6 | this warning is removed. 7 | -------------------------------------------------------------------------------- /docs/user_guide/encrypted_payload.rst: -------------------------------------------------------------------------------- 1 | Encrypted Payloads 2 | ================== 3 | 4 | .. warning:: 5 | This page is still under development and not complete. It will be so until 6 | this warning is removed. 7 | -------------------------------------------------------------------------------- /docs/user_guide.rst: -------------------------------------------------------------------------------- 1 | ========== 2 | User Guide 3 | ========== 4 | 5 | .. toctree:: 6 | :maxdepth: 2 7 | :caption: Contents: 8 | 9 | user_guide/user_selected_pcr_monitoring.rst 10 | user_guide/runtime_ima.rst 11 | user_guide/encrypted_payload.rst 12 | user_guide/revocation.rst 13 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # keylime-docs 2 | 3 | [![Documentation Status](https://readthedocs.org/projects/keylime-docs/badge/?version=latest)](https://keylime-docs.readthedocs.io/en/latest/?badge=latest) 4 | 5 | All Keylime documentation is formatted in [reStructuredText](https://en.wikipedia.org/wiki/ReStructuredText) 6 | 7 | The documentation project is built using [sphinx](http://www.sphinx-doc.org) 8 | 9 | Documentation is hosted on [readthedocs](https://readthedocs.org/) 10 | -------------------------------------------------------------------------------- /docs/security.rst: -------------------------------------------------------------------------------- 1 | ================ 2 | Securing Keylime 3 | ================ 4 | 5 | .. warning:: 6 | This page is still under development and not complete. It will be so until 7 | this warning is removed. 8 | 9 | System Hardening 10 | ---------------- 11 | 12 | TLS configuration 13 | ---------------- 14 | 15 | Reporting an issue 16 | ------------------ 17 | 18 | Please contact us directly at security@keylime.groups.io for any bug that might 19 | impact the security of this project. Do not use a github issue to report any 20 | potential security bugs. 21 | -------------------------------------------------------------------------------- /docs/Makefile: -------------------------------------------------------------------------------- 1 | # Minimal makefile for Sphinx documentation 2 | # 3 | 4 | # You can set these variables from the command line. 5 | SPHINXOPTS = 6 | SPHINXBUILD = sphinx-build 7 | SOURCEDIR = . 8 | BUILDDIR = _build 9 | 10 | # Put it first so that "make" without argument is like "make help". 11 | help: 12 | @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 13 | 14 | .PHONY: help Makefile 15 | 16 | # Catch-all target: route all unknown targets to Sphinx using the new 17 | # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). 18 | %: Makefile 19 | @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -------------------------------------------------------------------------------- /setup.cfg: -------------------------------------------------------------------------------- 1 | [metadata] 2 | name = keylime-docs 3 | version = 1.0.0 4 | license = MIT 5 | description = Keylime Documentation 6 | author = Keylime Developers 7 | author_email = keylime@groups.io 8 | url = http://keylime.github.io 9 | classifiers = 10 | Development Status :: 5 - Production/Stable 11 | Environment :: Web Environment 12 | Intended Audience :: Developers 13 | License :: OSI Approved :: MIT License 14 | Operating System :: OS Independent 15 | Programming Language :: Python 16 | Programming Language :: Python :: 2.7 17 | Programming Language :: Python :: 3.4 18 | Programming Language :: Python :: 3.5 19 | Programming Language :: Python :: 3.6 20 | Framework :: Django 21 | 22 | [options] 23 | packages = find: 24 | include_package_data = True 25 | zip_safe = False 26 | 27 | [tool:release] 28 | github_owner = keylime 29 | github_repo = keylime-docs 30 | -------------------------------------------------------------------------------- /docs/index.rst: -------------------------------------------------------------------------------- 1 | ===================== 2 | Keylime Documentation 3 | ===================== 4 | 5 | .. warning:: 6 | This documentation is still under development and not complete. It will be 7 | so until this warning is removed. 8 | 9 | Welcome to the Keylime Documentation site! 10 | 11 | Keylime is a TPM-based highly scalable remote boot attestation and runtime 12 | integrity measurement solution. Keylime enables cloud users to monitor remote 13 | nodes using a hardware based cryptographic root of trust. 14 | 15 | Keylime was originally born out of the security research team in MIT's Lincoln 16 | Laboratory and is now developed and maintained by the Keylime community. 17 | 18 | This Documentation site contains guides to install, use and administer keylime 19 | as well as guides to enable developers to make contributions to keylime 20 | or develop services against Keylime's Rest API(s). 21 | 22 | 23 | .. toctree:: 24 | :maxdepth: 2 25 | :caption: Contents: 26 | 27 | installation 28 | user_guide 29 | rest_apis 30 | developers 31 | security 32 | 33 | Indices and tables 34 | ================== 35 | 36 | * :ref:`genindex` 37 | * :ref:`modindex` 38 | * :ref:`search` 39 | -------------------------------------------------------------------------------- /docs/user_guide/user_selected_pcr_monitoring.rst: -------------------------------------------------------------------------------- 1 | User Selected PCR Monitoring 2 | ============================ 3 | 4 | .. warning:: 5 | This page is still under development and not complete. It will be so until 6 | this warning is removed. 7 | 8 | Using use the `tpm_policy` feature in Keylime, it is possible to mointor a 9 | remote machine for any given PCR. 10 | 11 | This can be used for Trusted Boot checks for both the `rhboot` shim loader and 12 | Trusted Grub 2. 13 | 14 | How to use 15 | ---------- 16 | 17 | Select which PCRs you would like Keylime to measure, by using the `tpm2_pcrlist` 18 | tool. 19 | 20 | Now you can set the PCR values as an array in either the `keylime.conf` file:: 21 | 22 | tpm_policy = {"22":["0000000000000000000000000000000000000001","0000000000000000000000000000000000000000000000000000000000000001","000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001","ffffffffffffffffffffffffffffffffffffffff","ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff","ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff"],"15":["0000000000000000000000000000000000000000","0000000000000000000000000000000000000000000000000000000000000000","000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000"]} 23 | 24 | Or you can add a node to using `keylime_tenant`:: 25 | 26 | keylime_tenant -v 127.0.0.1 -t 127.0.0.1 -f /root/excludes.txt \ 27 | --uuid D432FBB3-D2F1-4A97-9EF7-75BD81C00000 \ 28 | --whitelist /root/whitelist.txt \ 29 | --exclude /root/exclude.txt \ 30 | --tpm_policy {"22":["0000000000000000000000000000000000000001","0000000000000000000000000000000000000000000000000000000000000001","000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001","ffffffffffffffffffffffffffffffffffffffff","ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff","ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff"],"15":["0000000000000000000000000000000000000000","0000000000000000000000000000000000000000000000000000000000000000","000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000"]} \ 31 | -c add 32 | 33 | rhboot shim-loader 34 | ------------------ 35 | 36 | The following is sourced from the `rhboot shim repository _ 37 | please visit the upstream README to ensure information is still accurate 38 | 39 | The following PCRs are extended by shim: 40 | 41 | PCR4: 42 | - the Authenticode hash of the binary being loaded will be extended into 43 | PCR4 before SB verification. 44 | - the hash of any binary for which Verify is called through the shim_lock 45 | protocol 46 | 47 | PCR7: 48 | - Any certificate in one of our certificate databases that matches a binary 49 | we try to load will be extended into PCR7. That includes: 50 | - DBX - the system blacklist, logged as "dbx" 51 | - MokListX - the Mok blacklist, logged as "MokListX" 52 | - vendor_dbx - shim's built-in vendor blacklist, logged as "dbx" 53 | - DB - the system whitelist, logged as "db" 54 | - MokList the Mok whitelist, logged as "MokList" 55 | - vendor_cert - shim's built-in vendor whitelist, logged as "Shim" 56 | - shim_cert - shim's build-time generated whitelist, logged as "Shim" 57 | - MokSBState will be extended into PCR7 if it is set, logged as 58 | "MokSBState". 59 | 60 | PCR8: 61 | - If you're using the grub2 TPM patchset we cary in Fedora, the kernel command 62 | line and all grub commands (including all of grub.cfg that gets run) are 63 | measured into PCR8. 64 | 65 | PCR9: 66 | - If you're using the grub2 TPM patchset we cary in Fedora, the kernel, 67 | initramfs, and any multiboot modules loaded are measured into PCR9. 68 | 69 | PCR14: 70 | - MokList, MokListX, and MokSBState will be extended into PCR14 if they are 71 | set. 72 | 73 | 74 | 75 | 76 | e 77 | -------------------------------------------------------------------------------- /docs/rest_apis.rst: -------------------------------------------------------------------------------- 1 | ========== 2 | Rest API's 3 | ========== 4 | 5 | https://docs.readthedocs.io/en/stable/api/v2.html 6 | 7 | All Keylime APIs use `REST (Representational State Transfer)`. 8 | 9 | Authentication and authorization 10 | -------------------------------- 11 | 12 | Not yet implemented 13 | 14 | RESTful API for Keylime (v2) 15 | ---------------------------- 16 | 17 | Cloud verifier (CV) 18 | ~~~~~~~~~~~~~~~~~~ 19 | 20 | .. http:get:: /v2/agents/{agent_id:UUID} 21 | 22 | Get status of agent `agent_id` from CV 23 | 24 | .. http:post:: /v2/agents/{agent_id:UUID} 25 | 26 | Add new agent `instance_id` to CV 27 | 28 | **Requires JSON Body**: 29 | 30 | .. sourcecode:: js 31 | 32 | { 33 | “v” : key, 34 | “ip” : ipaddr, 35 | “port” : int, 36 | “operational_state” : int, 37 | “public_key” : key, 38 | “tpm_policy” : json, 39 | “vtpm_policy” : json, 40 | “metadata” : json, 41 | “ima_whitelist” : json, 42 | “accept_tpm_hash_algs”: list, 43 | “accept_tpm_encryption_algs”: list, 44 | “accept_tpm_signing_algs”: list, 45 | } 46 | 47 | .. http:delete:: /v2/agents/{agent_id:UUID} 48 | 49 | Terminate instance `agent_id` 50 | 51 | .. http:put:: /v2/agents/{agent_id:UUID}/reactivate 52 | 53 | Start agent `agent_id`` (for an already bootstrapped `agent_id` node) 54 | 55 | .. http:put:: /v2/agents/{agent_id:UUID}/stop 56 | 57 | Stop cv polling on `agent_id`, but don’t delete (for an already started `agent_id`) 58 | 59 | Cloud Agent 60 | ~~~~~~~~~~~ 61 | 62 | .. http:get:: /v2/keys/pubkey 63 | 64 | Retrieves agents public key 65 | 66 | .. http:post:: /v2/keys/vkey 67 | 68 | Send `v_key` to node 69 | 70 | **Requires JSON Body**: 71 | 72 | .. sourcecode:: js 73 | 74 | { 75 | “encrypted_key”: key, 76 | } 77 | 78 | .. http:post:: /v2/keys/ukey 79 | 80 | Send `u_key` to node (with optional payload) 81 | 82 | **Requires JSON Body**: 83 | 84 | .. sourcecode:: js 85 | 86 | { 87 | “auth_tag” : hmac, 88 | “encrypted _key”: key, 89 | “payload”: b64, (opt) 90 | } 91 | 92 | .. http:get:: /v2/keys/pubkey 93 | 94 | Get confirmation of bootstrap key derivation 95 | 96 | **Requires query parameters:** 97 | 98 | .. sourcecode:: js 99 | 100 | challenge : int 101 | 102 | .. http:get:: /v2/quotes/integrity 103 | 104 | Get integrity quote from node 105 | 106 | **Required parameters:** 107 | 108 | .. sourcecode:: js 109 | 110 | nonce : int 111 | mask : bitmask 112 | vmask : bitmask 113 | partial : bool 114 | 115 | Example: 116 | 117 | .. sourcecode:: bash 118 | 119 | /v2/quotes/integrity?nonce=#&mask=#&vmask=#&partial=# 120 | 121 | .. http:get:: /v2/quotes/identity 122 | 123 | Get identity quote from node 124 | 125 | **Required parameters:** 126 | 127 | .. sourcecode:: js 128 | 129 | nonce : int 130 | 131 | Example: 132 | 133 | .. sourcecode:: bash 134 | 135 | /v2/quotes/identity?nonce=# 136 | 137 | Cloud verifier (CV) 138 | ~~~~~~~~~~~~~~~~~~ 139 | 140 | .. http:get:: /v2/agents/ 141 | 142 | Get ordered list of registered agents 143 | 144 | .. http:get:: /v2/agents/{agent_id:UUID} 145 | 146 | Get AIK of agent `agent_id` 147 | 148 | .. http:post:: /v2/agents/{agent_id:UUID} 149 | 150 | Add agent `agent_id` to registrar 151 | 152 | **Requires JSON Body**: 153 | 154 | .. sourcecode:: js 155 | 156 | { 157 | “ek” : key, 158 | “ekcert” : cert, 159 | “aik” : key, 160 | “tpm_version”: TPM version, 161 | “aik_name” : key name, (tpm2) 162 | “ek_tpm” : TPM-format key (tpm2) 163 | } 164 | 165 | .. http:delete:: /v2/agents/{agent_id:UUID} 166 | 167 | Remove agent `agent_id` from registrar 168 | 169 | 170 | .. http:put:: /v2/agents/{agent_id:UUID}/activate 171 | 172 | Activate physical agent `agent_id` 173 | 174 | **Requires JSON Body**: 175 | 176 | .. sourcecode:: js 177 | 178 | { 179 | “auth_tag” : hmac, 180 | } 181 | 182 | .. http:put:: /v2/agents/{agent_id:UUID}/vactivate 183 | 184 | Activate virtual (vTPM) agent `agent_id` 185 | 186 | **Requires JSON Body**: 187 | 188 | .. sourcecode:: js 189 | 190 | { 191 | “deepquote” : b64, 192 | } 193 | 194 | Tenant WebApp 195 | ~~~~~~~~~~~~~ 196 | 197 | .. http:get:: /v2/agents/ 198 | 199 | Get ordered list of registered agents 200 | 201 | .. http:get:: /v2/agents/{agent_id:UUID} 202 | 203 | Get list of registered agents 204 | 205 | .. http:put:: /v2/agents/{agent_id:UUID} 206 | 207 | Start agent `agent_id` (For an already bootstrapped `agent_id` agent) 208 | 209 | .. http:post:: /v2/agents/{agent_id:UUID} 210 | 211 | Add agent `agent_id` to registrar 212 | 213 | **Requires JSON Body**: 214 | 215 | .. sourcecode:: js 216 | 217 | { 218 | “ip” : ipaddr, 219 | “keyfile_data” : base64, 220 | “keyfile_name” : string, (opt) 221 | “file_data” : base64, 222 | “file_name” : string, (opt) 223 | “ca_dir” : string, 224 | “ca_dir_pw” : string, 225 | “include_dir_data” : base64, 226 | “include_dir_name” : string, 227 | } 228 | 229 | .. http:get:: /v2/logs/ 230 | 231 | Get terminal log data 232 | 233 | .. http:get:: /v2/logs/{logType:string} 234 | 235 | Get terminal log data for given logType 236 | 237 | Optional query parameters: 238 | 239 | .. sourcecode:: bash 240 | 241 | pos : int, (opt) 242 | 243 | Example: 244 | 245 | .. sourcecode:: bash 246 | 247 | /v2/logs/tenant?pos=# 248 | 249 | RESTful API Responses for Keylime (v2) 250 | -------------------------------------- 251 | -------------------------------------------------------------------------------- /docs/conf.py: -------------------------------------------------------------------------------- 1 | # -*- coding: utf-8 -*- 2 | # 3 | # Configuration file for the Sphinx documentation builder. 4 | # 5 | # This file does only contain a selection of the most common options. For a 6 | # full list see the documentation: 7 | # http://www.sphinx-doc.org/en/master/config 8 | 9 | # -- Path setup -------------------------------------------------------------- 10 | 11 | # If extensions (or modules to document with autodoc) are in another directory, 12 | # add these directories to sys.path here. If the directory is relative to the 13 | # documentation root, use os.path.abspath to make it absolute, like shown here. 14 | # 15 | # import os 16 | # import sys 17 | # sys.path.insert(0, os.path.abspath('.')) 18 | 19 | 20 | # -- Project information ----------------------------------------------------- 21 | 22 | project = 'Keylime Documentation' 23 | copyright = '2019, Keylime Developers' 24 | author = 'Keylime Developers' 25 | 26 | # The short X.Y version 27 | version = '' 28 | # The full version, including alpha/beta/rc tags 29 | release = '3.0.0' 30 | 31 | 32 | # -- General configuration --------------------------------------------------- 33 | 34 | # If your documentation needs a minimal Sphinx version, state it here. 35 | # 36 | # needs_sphinx = '1.0' 37 | 38 | # Add any Sphinx extension module names here, as strings. They can be 39 | # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom 40 | # ones. 41 | extensions = [ 42 | 'sphinx.ext.viewcode', 43 | 'sphinx.ext.autosectionlabel', 44 | 'sphinx.ext.autodoc', 45 | 'sphinx.ext.intersphinx', 46 | 'sphinx.ext.githubpages', 47 | 'sphinxcontrib.httpdomain', 48 | 'sphinx_tabs.tabs', 49 | 'sphinx-prompt', 50 | 'recommonmark', 51 | 'notfound.extension', 52 | ] 53 | 54 | # Add any paths that contain templates here, relative to this directory. 55 | templates_path = ['_templates'] 56 | 57 | # The suffix(es) of source filenames. 58 | # You can specify multiple suffix as a list of string: 59 | # 60 | # source_suffix = ['.rst', '.md'] 61 | source_suffix = '.rst' 62 | 63 | # The master toctree document. 64 | master_doc = 'index' 65 | 66 | # The language for content autogenerated by Sphinx. Refer to documentation 67 | # for a list of supported languages. 68 | # 69 | # This is also used if you do content translation via gettext catalogs. 70 | # Usually you set "language" from the command line for these cases. 71 | language = None 72 | 73 | # List of patterns, relative to source directory, that match files and 74 | # directories to ignore when looking for source files. 75 | # This pattern also affects html_static_path and html_extra_path. 76 | exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] 77 | 78 | # The name of the Pygments (syntax highlighting) style to use. 79 | pygments_style = None 80 | 81 | 82 | # -- Options for HTML output ------------------------------------------------- 83 | 84 | # The theme to use for HTML and HTML Help pages. See the documentation for 85 | # a list of builtin themes. 86 | # 87 | #html_theme = 'alabaster' 88 | html_theme = 'sphinx_rtd_theme' 89 | # Theme options are theme-specific and customize the look and feel of a theme 90 | # further. For a list of options available for each theme, see the 91 | # documentation. 92 | # 93 | # html_theme_options = {} 94 | 95 | # Add any paths that contain custom static files (such as style sheets) here, 96 | # relative to this directory. They are copied after the builtin static files, 97 | # so a file named "default.css" will overwrite the builtin "default.css". 98 | html_static_path = ['_static'] 99 | 100 | # Custom sidebar templates, must be a dictionary that maps document names 101 | # to template names. 102 | # 103 | # The default sidebars (for documents that don't match any pattern) are 104 | # defined by theme itself. Builtin themes are using these templates by 105 | # default: ``['localtoc.html', 'relations.html', 'sourcelink.html', 106 | # 'searchbox.html']``. 107 | # 108 | # html_sidebars = {} 109 | 110 | 111 | # -- Options for HTMLHelp output --------------------------------------------- 112 | 113 | # Output file base name for HTML help builder. 114 | htmlhelp_basename = 'KeylimeDocumentationdoc' 115 | 116 | 117 | # -- Options for LaTeX output ------------------------------------------------ 118 | 119 | latex_elements = { 120 | # The paper size ('letterpaper' or 'a4paper'). 121 | # 122 | # 'papersize': 'letterpaper', 123 | 124 | # The font size ('10pt', '11pt' or '12pt'). 125 | # 126 | # 'pointsize': '10pt', 127 | 128 | # Additional stuff for the LaTeX preamble. 129 | # 130 | # 'preamble': '', 131 | 132 | # Latex figure (float) alignment 133 | # 134 | # 'figure_align': 'htbp', 135 | } 136 | 137 | # Grouping the document tree into LaTeX files. List of tuples 138 | # (source start file, target name, title, 139 | # author, documentclass [howto, manual, or own class]). 140 | latex_documents = [ 141 | (master_doc, 'KeylimeDocumentation.tex', 'Keylime Documentation Documentation', 142 | 'Keylime Developers', 'manual'), 143 | ] 144 | 145 | 146 | # -- Options for manual page output ------------------------------------------ 147 | 148 | # One entry per manual page. List of tuples 149 | # (source start file, name, description, authors, manual section). 150 | man_pages = [ 151 | (master_doc, 'keylimedocumentation', 'Keylime Documentation Documentation', 152 | [author], 1) 153 | ] 154 | 155 | 156 | # -- Options for Texinfo output ---------------------------------------------- 157 | 158 | # Grouping the document tree into Texinfo files. List of tuples 159 | # (source start file, target name, title, author, 160 | # dir menu entry, description, category) 161 | texinfo_documents = [ 162 | (master_doc, 'KeylimeDocumentation', 'Keylime Documentation Documentation', 163 | author, 'KeylimeDocumentation', 'One line description of project.', 164 | 'Miscellaneous'), 165 | ] 166 | 167 | 168 | # -- Options for Epub output ------------------------------------------------- 169 | 170 | # Bibliographic Dublin Core info. 171 | epub_title = project 172 | 173 | # The unique identifier of the text. This can be a ISBN number 174 | # or the project homepage. 175 | # 176 | # epub_identifier = '' 177 | 178 | # A unique identification for the text. 179 | # 180 | # epub_uid = '' 181 | 182 | # A list of files that should not be packed into the epub file. 183 | epub_exclude_files = ['search.html'] 184 | 185 | 186 | # -- Extension configuration ------------------------------------------------- 187 | -------------------------------------------------------------------------------- /docs/user_guide/runtime_ima.rst: -------------------------------------------------------------------------------- 1 | Run-time Integrity Monitoring 2 | ============================= 3 | 4 | Keylimes run-time integrity monitoring requires the set up of Linux IMA. 5 | 6 | You should refer to your Linux Distributions documentation to enable IMA, but 7 | as a general guide most recent versions already have `CONFIG_IMA` toggled to 8 | `Y` as a value during Kernel compile. 9 | 10 | It is then just a case of deploying an `ima-policy` file. On a Fedora or Debian 11 | system, the file is situated in `/etc/ima/ima-policy`. 12 | 13 | For configuration of your IMA policy, please refer to the `IMA Documentation `_ 14 | 15 | Within Keylime we use the following for demonstration:: 16 | 17 | # PROC_SUPER_MAGIC 18 | dont_measure fsmagic=0x9fa0 19 | # SYSFS_MAGIC 20 | dont_measure fsmagic=0x62656572 21 | # DEBUGFS_MAGIC 22 | dont_measure fsmagic=0x64626720 23 | # TMPFS_MAGIC 24 | dont_measure fsmagic=0x01021994 25 | # RAMFS_MAGIC 26 | dont_measure fsmagic=0x858458f6 27 | # SECURITYFS_MAGIC 28 | dont_measure fsmagic=0x73636673 29 | # MEASUREMENTS 30 | measure func=BPRM_CHECK 31 | measure func=FILE_MMAP mask=MAY_EXEC 32 | measure func=MODULE_CHECK uid=0 33 | 34 | This default policy measures all executables in `bprm_check`, all files `mmapped` 35 | executable in `file_mmap` and module checks. 36 | 37 | Once your `ima-policy` is in place, reboot your machine (or even better have it 38 | present in your image for first boot). 39 | 40 | You can then verify IMA is measuring your system:: 41 | 42 | # head -5 /sys/kernel/security/ima/ascii_runtime_measurements 43 | PCR template-hash filedata-hash filename-hint 44 | 10 3c93cea361cd6892bc8b9e3458e22ce60ef2e632 ima-ng sha1:ac7dd11bf0e3bec9a7eb2c01e495072962fb9dfa boot_aggregate 45 | 10 3d1452eb1fcbe51ad137f3fc21d3cf4a7c2e625b ima-ng sha1:a212d835ca43d7deedd4ee806898e77eab53dafa /usr/lib/systemd/systemd 46 | 10 e213099a2bf6d88333446c5da617e327696f9eb4 ima-ng sha1:6da34b1b7d2ca0d5ca19e68119c262556a15171d /usr/lib64/ld-2.28.so 47 | 10 7efd8e2a3da367f2de74b26b84f20b37c692b9f9 ima-ng sha1:af78ea0b455f654e9237e2086971f367b6bebc5f /usr/lib/systemd/libsystemd-shared-239.so 48 | 10 784fbf69b54c99d4ae82c0be5fca365a8272414e ima-ng sha1:b0c601bf82d32ff9afa34bccbb7e8f052c48d64e /etc/ld.so.cache 49 | 50 | Keylime IMA whitelists 51 | ---------------------- 52 | 53 | A whitelist is a set of "golden" cryptographic hashes of a files un-tampered 54 | state. 55 | 56 | The structure of the white list is a hash followed by a full POSIX path to the 57 | file:: 58 | 59 | ffe3ad4c395985d143bd0e45a9a1dd09aac21b91 /path/to/file 60 | 61 | Keylime will load the whitelist into the Keylime Verifier. Keylime will then 62 | poll tpm quotes to `PCR 10` on the agents TPM and validate the agents file(s) 63 | state against the whitelist. If the object has been tampered with, the hashes 64 | will not match and Keylime will place the agent into a failed state. Likewise, 65 | if any files invoke the actions stated in `ima-policy` that are not matched in 66 | the whitelist, keylime will place the agent into a failed state. 67 | 68 | Generate a whitelist 69 | ~~~~~~~~~~~~~~~~~~~~ 70 | 71 | Keylime provides a script to generate whitelists from `initramfs`, but this is 72 | only a guide. We encourage developers / users of Keylime to be creative and come 73 | up with their own process for securely creating and maintaining a whitelist. 74 | 75 | The `create_whitelist.sh` script is `available here `_ 76 | 77 | Run the script as follows:: 78 | 79 | # create_whitelist.sh whitelist.txt [hash-algo] 80 | 81 | With `[hash-algo]` being `sha1sum`, `sha256sum` (note, you need the OpenSSL app 82 | installed to have the shasum CLI applications available). 83 | 84 | This will then result in `whitelist.txt` being available for Agent provisioning. 85 | 86 | .. warning:: 87 | It’s best practice to create the whitelist in a secure environment. Ideally, 88 | this should be on a fully encrypted, air gapped computer that is permanently 89 | isolated from the Internet. Disable all network cards and sign the whitelist 90 | hash to ensure no tampering occurs when transferring to other machines. 91 | 92 | Alongside building a whitelist from `initramfs`, you could also generate good 93 | hashes for your applications files or admin scripts that will run on the 94 | remotely attested machine. 95 | 96 | Excludes List 97 | ~~~~~~~~~~~~~ 98 | 99 | An excludes list can be utilised to exclude any file or path. The excludes list 100 | supports standard regular expressions, for example the `tmp` directory can be 101 | ignored:: 102 | 103 | /tmp/* 104 | 105 | 106 | Remotely Provision Agents 107 | ~~~~~~~~~~~~~~~~~~~~~~~~~ 108 | 109 | Now that we have our whitelist available, we can send it to the verifier. 110 | 111 | .. note:: 112 | If you're using a TPM Emulator (for example with the ansible-keylime-tpm-emulator, you will also need 113 | to run the keylime ima emulator. To do this, open a terminal and run `keylime_ima_emulator` 114 | 115 | Using the `keylime_tenant` we can send the whitelist and our excludes list as 116 | follows:: 117 | 118 | keylime_tenant -v -t -f /path/excludes.txt --uuid D432FBB3-D2F1-4A97-9EF7-75BD81C00000 --whitelist /path/whitelist.txt --exclude /path/excludes.txt 119 | 120 | .. note:: 121 | If your agent is already registered, you can use `-c update` 122 | 123 | Should you prefer, you can set the values `ima_whitelist` & `ima_excludelist` 124 | within `/etc/keylime.conf`, you can then use `default` as follows:: 125 | 126 | `keylime_tenant -v 127.0.0.1 -t neptune -f /root/excludes.txt --uuid D432FBB3-D2F1-4A97-9EF7-75BD81C00000 --whitelist default --exclude default` 127 | 128 | The whitelist can also be uploaded using the WebApp: 129 | 130 | .. image:: ../images/whitelist_ui.png 131 | 132 | How can I test this? 133 | -------------------- 134 | 135 | Create a script that does anything (for example `echo "hello world"`) that is not 136 | present in your whitelist or the excludes list. Run the script as root on the 137 | agent machine. You will then see the following output on the verifier showing 138 | the agent status change to failed:: 139 | 140 | keylime.tpm - INFO - Checking IMA measurement list... 141 | keylime.ima - WARNING - File not found in whitelist: /root/evil_script.sh 142 | keylime.ima - ERROR - IMA ERRORS: template-hash 0 fnf 1 hash 0 good 781 143 | keylime.cloudverifier - WARNING - agent D432FBB3-D2F1-4A97-9EF7-75BD81C00000 failed, stopping polling 144 | -------------------------------------------------------------------------------- /docs/developers.rst: -------------------------------------------------------------------------------- 1 | =================== 2 | KeyLime Development 3 | =================== 4 | 5 | Contributing 6 | ------------ 7 | 8 | When contributing any keylime repository, please first discuss the change you wish 9 | to make via an issue in the relevant repository for your change or email to the 10 | `keylime mailing list `_ 11 | 12 | Pull Request Process 13 | ~~~~~~~~~~~~~~~~~~~~ 14 | 15 | 1. Create an `issue `_ 16 | outlining the fix or feature. 17 | 2. Fork the keylime repository to your own github account and clone it locally. 18 | 3. Hack on your changes. 19 | 4. Update the README.md or documentation with details of changes to any 20 | interface, this includes new environment variables, exposed ports, useful 21 | file locations, CLI parameters and configuration values. 22 | 5. Add and commit your changes with some descriptive text on the nature of the 23 | change / feature in your commit message. Also reference the issue raised at 24 | [1] as follows: `Fixes #45`. See `the following link `_ 25 | for more message types 26 | 6. Ensure that CI passes, if it fails, fix the failures. 27 | 7. Every pull request requires a review from the `core keylime team `_ 28 | 8. If your pull request consists of more than one commit, please squash your 29 | commits as described in see :ref:`squash-commits`. 30 | 31 | Commit Message Guidelines 32 | ------------------------- 33 | 34 | We follow the commit formatting recommendations found on `Chris Beams' How to Write a Git Commit Message article `_. 35 | 36 | Well formed commit messages not only help reviewers understand the nature of 37 | the Pull Request, but also assists the release process where commit messages 38 | are used to generate release notes. 39 | 40 | A good example of a commit message would be as follows:: 41 | 42 | Summarize changes in around 50 characters or less 43 | 44 | More detailed explanatory text, if necessary. Wrap it to about 72 45 | characters or so. In some contexts, the first line is treated as the 46 | subject of the commit and the rest of the text as the body. The 47 | blank line separating the summary from the body is critical (unless 48 | you omit the body entirely); various tools like `log`, `shortlog` 49 | and `rebase` can get confused if you run the two together. 50 | 51 | Explain the problem that this commit is solving. Focus on why you 52 | are making this change as opposed to how (the code explains that). 53 | Are there side effects or other unintuitive consequences of this 54 | change? Here's the place to explain them. 55 | 56 | Further paragraphs come after blank lines. 57 | 58 | - Bullet points are okay, too 59 | 60 | - Typically a hyphen or asterisk is used for the bullet, preceded 61 | by a single space, with blank lines in between, but conventions 62 | vary here 63 | 64 | If you use an issue tracker, put references to them at the bottom, 65 | like this: 66 | 67 | Resolves: #123 68 | See also: #456, #789 69 | 70 | Note the `Resolves #123` tag, this references the issue raised and allows us to 71 | ensure issues are associated and closed when a pull request is merged. 72 | 73 | Please refer to `the github help page on message types `_ 74 | for a complete list of issue references. 75 | 76 | .. _squash-commits: 77 | 78 | Squash Commits 79 | -------------- 80 | 81 | Should your pull request consist of more than one commit (perhaps due to 82 | a change being requested during the review cycle), please perform a git squash 83 | once a reviewer has approved your pull request. 84 | 85 | A squash can be performed as follows. Let's say you have the following commits:: 86 | 87 | initial commit 88 | second commit 89 | final commit 90 | 91 | Run the command below with the number set to the total commits you wish to 92 | squash (in our case 3 commits):: 93 | 94 | git rebase -i HEAD~3 95 | 96 | You default text editor will then open up and you will see the following:: 97 | 98 | pick eb36612 initial commit 99 | pick 9ac8968 second commit 100 | pick a760569 final commit 101 | 102 | # Rebase eb1429f..a760569 onto eb1429f (3 commands) 103 | 104 | We want to rebase on top of our first commit, so we change the other two commits 105 | to `squash`:: 106 | 107 | pick eb36612 initial commit 108 | squash 9ac8968 second commit 109 | squash a760569 final commit 110 | 111 | After this, should you wish to update your commit message to better summarise 112 | all of your pull request, run:: 113 | 114 | git commit --amend 115 | 116 | You will then need to force push (assuming your initial commit(s) were posted 117 | to github):: 118 | 119 | git push origin your-branch --force 120 | 121 | Docker Development Environment 122 | ------------------------------ 123 | 124 | The following is a guide to mounting your local repository as a Docker volume 125 | and performing a test run using a TPM simulator. This will replicate the same 126 | test that occurs within the KeyLime CI gate for keylime. 127 | 128 | This requires a working installation of Docker. See your distributions guide on 129 | how to set that up. 130 | 131 | As an example, on Fedora 29:: 132 | 133 | sudo dnf -y install dnf-plugins-core 134 | sudo dnf install docker-ce docker-ce-cli containerd.io 135 | sudo usermod -aG docker $USER 136 | sudo systemctl enable docker 137 | sudo systemctl start docker 138 | 139 | Note: login and out of your shell, if you want to run docker as `$USER` 140 | 141 | Save the following script to your local machine (tip: create an alias to call the 142 | script in an easy to remember way):: 143 | 144 | #!/bin/bash 145 | 146 | # Your local keylime (you should likely change this) 147 | REPO="/home/${USER}/keylime" 148 | 149 | # keylime images 150 | tpm12image="lukehinds/keylime-ci-tpm12" 151 | tpm12tag="v550" 152 | tpm20image="lukehinds/keylime-ci-tpm20" 153 | tpm20tag="v301" 154 | 155 | echo -e "Grabbing latest images" 156 | 157 | docker pull ${tpm12image}:${tpm12tag} 158 | docker pull ${tpm20image}:${tpm20tag} 159 | 160 | function tpm1 { 161 | container_id=$(mktemp) 162 | docker run --detach --privileged \ 163 | -v $REPO:/root/keylime \ 164 | -it ${tpm12image}:${tpm12tag} >> ${container_id} 165 | docker exec -u 0 -it --tty "$(cat ${container_id})" \ 166 | /bin/sh -c 'cd /root/keylime/test; chmod +x ./run_tests.sh; ./run_tests.sh -s openssl' 167 | docker stop "$(cat ${container_id})" 168 | docker rm "$(cat ${container_id})" 169 | } 170 | 171 | function tpm2 { 172 | container_id=$(mktemp) 173 | docker run --detach --privileged \ 174 | -v $REPO:/root/keylime \ 175 | -v /sys/fs/cgroup:/sys/fs/cgroup:ro \ 176 | -it ${tpm20image}:${tpm20tag} >> ${container_id} 177 | docker exec -u 0 -it --tty "$(cat ${container_id})" \ 178 | /bin/bash /root/keylime/.ci/test_wrapper.sh 179 | docker stop "$(cat ${container_id})" 180 | docker rm "$(cat ${container_id})" 181 | } 182 | 183 | while true; do 184 | echo -e "" 185 | read -p "Do you wish to test against TPM1.2(a) / TPM 2.0(b) or q(quit): " abq 186 | case $abq in 187 | [a]* ) tpm1;; 188 | [b]* ) tpm2;; 189 | [q]* ) exit;; 190 | * ) echo "Please answer 1, 2 q(quit)";; 191 | esac 192 | done 193 | -------------------------------------------------------------------------------- /docs/installation.rst: -------------------------------------------------------------------------------- 1 | Installation 2 | ============ 3 | 4 | There are three current methods for installing Keylime, the ansible role, the 5 | keylime installer or a manual installation. 6 | 7 | Ansible Keylime Roles 8 | --------------------- 9 | 10 | An Ansible role to deploy `Keylime `_ 11 | , alongside the `Keylime rust cloud agent `_ 12 | 13 | .. warning:: 14 | Please note that the rust cloud agent is still under early stages of Development. 15 | Those wishing to test drive keylimes functionality should use the existing 16 | python based cloud agent `keylime_agent` until later notice. 17 | 18 | This role deploys keylime for use with a Hardware TPM. 19 | 20 | Should you wish to deploy Keylime with a software TPM emulator for development 21 | or getting your feet wet, use the `Ansible Keylime Soft TPM `_ 22 | role instead. 23 | 24 | Usage 25 | ~~~~~ 26 | 27 | Download or clone `Ansible Keylime `_ 28 | from its repository and follow the usage section. 29 | 30 | Run the example playbook against your target remote host(s):: 31 | 32 | ansible-playbook -i your_hosts playbook.yml 33 | 34 | TPM Version Control (Software TPM) 35 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 36 | 37 | **Ansible Keylime Soft TPM** provides two role types for both 1.2 and 2.0 TPM 38 | versions. 39 | 40 | Either TPM version 1.2 or TPM 2.0 support can be configured by simply changing 41 | the role in the `playbook.yml` file `here `_ 42 | 43 | For TPM 2.0 use:: 44 | 45 | - ansible-keylime-tpm20 46 | 47 | For TPM 1.20 use:: 48 | 49 | - ansible-keylime-tpm12 50 | 51 | Both roles will deploy the relevant TPM 1.2 Emulator (tpm4720) or 2.0 Emulator 52 | (IBM software TPM). 53 | 54 | Vagrant 55 | ~~~~~~~ 56 | 57 | If you prefer, a `Vagrantfile` is available for provisioning. 58 | 59 | Clone the repository and then simply run:: 60 | 61 | vagrant up --provider --provision 62 | 63 | For example, using libvirt:: 64 | 65 | vagrant up --provider libvirt --provision 66 | 67 | 68 | For example, using VirtualBox:: 69 | 70 | vagrant up --provider virtualbox --provision 71 | 72 | Once the VM is started, vagrant ssh into the VM and run `sudo su` - to 73 | become root. 74 | 75 | You can then start the various components using commands:: 76 | 77 | keylime_verifier 78 | keylime_registrar 79 | keylime_agent 80 | 81 | WebApp 82 | ~~~~~~ 83 | 84 | The web application can be started with the command `keylime_webapp`. If using 85 | Vagrant, port 443 will be forwarded from the guest to port 8443 on the host. 86 | 87 | This will result in the web application being available on url: 88 | 89 | https://localhost:8443/webapp/ 90 | 91 | Rust Cloud agent 92 | ~~~~~~~~~~~~~~~ 93 | 94 | To start the rust cloud agent, navigate to it's repository directory and use 95 | cargo to run:: 96 | 97 | [root@localhost rust-keylime]# RUST_LOG=keylime_agent=trace cargo run 98 | Finished dev [unoptimized + debuginfo] target(s) in 0.28s 99 | Running `target/debug/keylime_agent` 100 | INFO keylime_agent > Starting server... 101 | INFO keylime_agent > Listening on http://127.0.0.1:1337 102 | 103 | Keylime Bash installer 104 | ---------------------- 105 | 106 | Keylime requires Python 2.7.10 or newer for proper TLS support. 107 | 108 | Installation can be performed via an automated shell script, `installer.sh`. The 109 | following command line options are available:: 110 | 111 | Usage: ./installer.sh [option...] 112 | Options: 113 | -k Download Keylime (stub installer mode) 114 | -o Use OpenSSL instead of CFSSL 115 | -t Create tarball with keylime_agent 116 | -m Use modern TPM 2.0 libraries (vs. TPM 1.2) 117 | -s Install TPM in socket/simulator mode (vs. chardev) 118 | -p PATH Use PATH as Keylime path 119 | -h This help info 120 | 121 | Note that CFSSL is required if you want to support revocation. As noted above, do not use 122 | the TPM emulator option `-s` in production systems. 123 | 124 | Docker (Development Only) 125 | ------------------------- 126 | 127 | Python keylime and related emulators can also be deployed using Docker. 128 | Since this docker configuration currently uses a TPM emulator, 129 | it should only be used for development or testing and NOT in production. 130 | 131 | Please see either the Dockerfiles 132 | `here `_ or our 133 | local CI script 134 | `here `_ 135 | which will automate the build and pull of keylime on TPM 1.2 or 2.0. 136 | 137 | Manual 138 | ------ 139 | 140 | Keylime requires Python 2.7.10 or newer for proper TLS support. This is newer than 141 | some LTS distributions like Ubuntu 14.04 or CentOS 7. See google for instructions 142 | on how to get a newer Python onto those platforms. 143 | 144 | Python-based prerequisites 145 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ 146 | 147 | .. note:: 148 | The following outlines installing Keylime under the Python 2 environment, 149 | work is underway to port Keylime to Python 3. 150 | 151 | The following python packages are required: 152 | 153 | * pycryptodomex>=3.4.1 154 | * tornado>=4.3 155 | * m2crypto>=0.21.1 156 | * pyzmq>=14.4 157 | * setuptools>=0.7 158 | * python-dev 159 | * pyyaml 160 | 161 | The latter of these are usually available as distro packages. See `installer.sh `_ 162 | for more information if you want to install them this way. You can also let keylime's `setup.py` 163 | install them via PyPI. 164 | 165 | TPM 1.2 Support 166 | ~~~~~~~~~~~~~~~ 167 | 168 | You also need a patched version of tpm4720 the IBM software TPM emulator and 169 | utilities. This is available `here `_ 170 | Even if you are using keylime with a real TPM, you must install the IBM emulator 171 | because keylime uses the command line utilities that come with it. 172 | See README.md in that project for detailed instructions on how to build and install it. 173 | 174 | The brief synopsis of a quick build/install (after installing dependencies) is:: 175 | 176 | git clone https://github.com/keylime/tpm4720-keylime.git 177 | cd tpm4720-keylime/libtpm 178 | ./comp-chardev.sh 179 | sudo make install 180 | 181 | To build tpm4720 to use the TPM emulator replace `./comp-chardev.sh` with `./comp-sockets.sh`. 182 | 183 | To ensure that you have the patched version installed ensure that you have 184 | the `encaik` utility in your path. 185 | 186 | TPM 2.0 Support 187 | ~~~~~~~~~~~~~~~ 188 | 189 | Keylime uses the Intel TPM2 software set to provide TPM 2.0 support. You will 190 | need to install the tpm2-tss software stack (available `here `_) as well as a patched version of the 191 | tpm2-tools utilities available `here`_. 192 | See README.md in these projects for detailed instructions on how to build and install. 193 | 194 | The brief synopsis of a quick build/install (after installing dependencies) is:: 195 | 196 | # tpm2-tss 197 | git clone https://github.com/tpm2-software/tpm2-tss.git tpm2-tss 198 | pushd tpm2-tss 199 | ./bootstrap 200 | ./configure --prefix=/usr 201 | make 202 | sudo make install 203 | popd 204 | # tpm2-tools 205 | git clone https://github.com/keylime/tpm2-tools.git tpm2-tools 206 | pushd tpm2-tools 207 | ./bootstrap 208 | ./configure --prefix=/usr/local 209 | make 210 | sudo make install 211 | 212 | 213 | To ensure that you have the patched version installed ensure that you have 214 | the `tpm2_checkquote` utility in your path. 215 | 216 | TPM 2.0 Resource Manager 217 | ~~~~~~~~~~~~~~~~~~~~~~~~ 218 | 219 | Note that it is recommended that you use the tpm2-abrmd resource manager 220 | (available at https://github.com/tpm2-software/tpm2-abrmd) as well instead of 221 | communicating directly with the TPM. See README.md at that project for 222 | detailed instructions on how to build and install. 223 | 224 | A brief, workable example for Ubuntu 18 LTS systems is:: 225 | 226 | sudo useradd --system --user-group tss 227 | git clone https://github.com/tpm2-software/tpm2-abrmd.git tpm2-abrmd 228 | pushd tpm2-abrmd 229 | ./bootstrap 230 | ./configure --with-dbuspolicydir=/etc/dbus-1/system.d \ 231 | --with-systemdsystemunitdir=/lib/systemd/system \ 232 | --with-systemdpresetdir=/lib/systemd/system-preset \ 233 | --datarootdir=/usr/share 234 | make 235 | sudo make install 236 | sudo ldconfig 237 | sudo pkill -HUP dbus-daemon 238 | sudo systemctl daemon-reload 239 | sudo service tpm2-abrmd start 240 | export TPM2TOOLS_TCTI="tabrmd:bus_name=com.intel.tss2.Tabrmd" 241 | 242 | # NOTE: if using swtpm2 emulator, you need to run the tpm2-abrmd service as:: 243 | 244 | sudo -u tss /usr/local/sbin/tpm2-abrmd --tcti=mssim & 245 | 246 | Alternatively, it is also possible, though not recommended, to communicate 247 | directly with the TPM (and not use a resource manager). This can be done by 248 | setting the environment var `TPM2TOOLS_TCTI` to the appropriate value: 249 | 250 | To talk directly to the swtpm2 emulator:: 251 | 252 | export TPM2TOOLS_TCTI="mssim:port=2321"` 253 | 254 | To talk directly to a real TPM:: 255 | 256 | export TPM2TOOLS_TCTI="device:/dev/tpm0" 257 | 258 | Install Keylime 259 | ~~~~~~~~~~~~~~~ 260 | 261 | You're finally ready to install keylime:: 262 | 263 | sudo python setup.py install 264 | 265 | To run on OSX 10.11+ 266 | ~~~~~~~~~~~~~~~~~~~~ 267 | 268 | You need to build m2crypto from source with:: 269 | 270 | brew install openssl 271 | git clone https://gitlab.com/m2crypto/m2crypto.git 272 | python setup.py build build_ext --openssl=/usr/local/opt/openssl/ 273 | sudo -E python setup.py install build_ext --openssl=/usr/local/opt/openssl/ 274 | 275 | 276 | Optional Requirements 277 | ~~~~~~~~~~~~~~~~~~~~~ 278 | 279 | If you want to support revocation, you also need to have cfssl installed and in your 280 | path on the tenant agent. It can be obtained from `here `_. You 281 | will also need to set ca_implementation to "cfssl" instead of "openssl" in `/etc/keylime.conf`. 282 | 283 | Database support 284 | --------------------- 285 | 286 | Keylime supports the following databases:: 287 | 288 | * SQLite 289 | * PostgreSQL 290 | * MySQL 291 | * Oracle 292 | * Microsoft SQL Server 293 | 294 | SQLite is supported as default. 295 | 296 | Each database is configured within `/etc/keylime.conf` for both the keylime_verifier 297 | and keylime_registrar databases. 298 | 299 | SQLite 300 | ~~~~~~ 301 | 302 | The following illustrates examples for SQLite and PostgreSQL:: 303 | 304 | drivername = sqlite 305 | username = '' 306 | password = '' 307 | host = '' 308 | port = '' 309 | database = cv_data.sqlite 310 | query = '' 311 | 312 | PostgreSQL 313 | ~~~~~~~~~~ 314 | 315 | For PostgreSQL you will need to install the database first and set up a user 316 | account:: 317 | 318 | drivername = postgres 319 | username = keylime 320 | password = allyourbase 321 | host = localhost 322 | port = 5432 323 | database = keylime_db 324 | query = '' 325 | 326 | For details on other platforms, please refer to the SQLAlchemy documentation 327 | on `engine configuration `_. 328 | --------------------------------------------------------------------------------