{"id":22225062,"url":"https://github.com/stringlytyped/keylime","last_synced_at":"2025-07-17T19:34:44.016Z","repository":{"id":126215835,"uuid":"599641605","full_name":"stringlytyped/keylime","owner":"stringlytyped","description":"A CNCF Project to Bootstrap \u0026 Maintain Trust on the Edge / Cloud and IoT","archived":false,"fork":false,"pushed_at":"2023-02-22T10:32:18.000Z","size":15323,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-03-25T08:23:21.754Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://keylime.dev","language":"Python","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stringlytyped.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/security.rst","support":null,"governance":"GOVERNANCE.md","roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-02-09T15:18:06.000Z","updated_at":"2023-03-07T12:11:03.000Z","dependencies_parsed_at":null,"dependency_job_id":"bc14af73-7189-494b-b2ff-773f46ada884","html_url":"https://github.com/stringlytyped/keylime","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/stringlytyped/keylime","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stringlytyped%2Fkeylime","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stringlytyped%2Fkeylime/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stringlytyped%2Fkeylime/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stringlytyped%2Fkeylime/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stringlytyped","download_url":"https://codeload.github.com/stringlytyped/keylime/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stringlytyped%2Fkeylime/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262756044,"owners_count":23359459,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-03T00:14:57.742Z","updated_at":"2025-06-30T10:32:30.508Z","avatar_url":"https://github.com/stringlytyped.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Keylime\n\n[![Slack CNCF chat](https://img.shields.io/badge/Chat-CNCF%20Slack-informational)](https://cloud-native.slack.com/archives/C01ARE2QUTZ)\n[![Docs Status](https://readthedocs.org/projects/keylime/badge/?version=latest)](https://keylime.readthedocs.io/en/latest/?badge=latest)\n\n![keylime](docs/keylime.png?raw=true \"Title\")\n\nKeylime is an open-source scalable trust system harnessing TPM Technology.\n\nKeylime provides an end-to-end solution for bootstrapping hardware rooted\ncryptographic trust for remote machines, the provisioning of encrypted payloads, \nand run-time system integrity monitoring. It also provides a flexible\nframework for the remote attestation of any given `PCR` (Platform Configuration\nRegister). Users can create their own customized actions that will trigger when\na machine fails its attested measurements.\n\nKeylime's mission is to make TPM Technology easily accessible to developers and\nusers alike, without the need for a deep understanding of the lower levels of a\nTPM's operations. Amongst many scenarios, it well suited to tenants who need to\nremotely attest machines not under their own full control (such as a consumer of\nhybrid cloud or a remote Edge / IoT device in an insecure physical tamper prone\nlocation.)\n\nKeylime can be driven with a CLI application and a set of RESTful APIs.\n\nKeylime consists of three main components; The Verifier, Registrar and the\nAgent.\n\n* The Verifier continuously verifies the integrity state of the machine that\nthe agent is running on.\n\n* The Registrar is a database of all agents registered\nwith Keylime and hosts the public keys of the TPM vendors.\n\n* The Agent is deployed to the remote machine that is to be measured or provisioned\nwith secrets stored within an encrypted payload released once trust is established.\n\n### Rust based Keylime Agent\n\nThe verifier, registrar, and agent are all developed in Python and situated\nin this repository `keylime`. The agent was ported to the\n[Rust programming language](https://www.rust-lang.org). The code can be found \nin the [rust-keylime repository](https://github.com/keylime/rust-keylime).\n\nThe decision was made to port the agent to Rust, as rust is a low-level\nperformant systems language designed with security as a central tenet, by means\nof the rust compiler's ownership model.\n\nStarting with the 0.1.0 release of the Rust based Keylime agent, this agent is now the official agent.\n\n| IMPORTANT: The Python version is deprecated and will be removed with the next major version (7.0.0)! |\n|------------------------------------------------------------------------------------------------------|\n\n\n### TPM Support\n\nKeylime supports TPM version *2.0*.\n\nKeylime can be used with a hardware TPM, or a software TPM emulator for\ndevelopment, testing, or demonstration purposes.  However, DO NOT USE keylime in\nproduction with a TPM emulator!  A software TPM emulator does not provide a\nhardware root of trust and dramatically lowers the security benefits of using\nkeylime.\n\nA hardware TPM should always be used when real secrets and trust is required.\n\n## Table of Contents\n\n* [Installation](#installation)\n  * [Automated](#automated)\n  * [Manual](#manual)\n* [Making sure your TPM is ready for keylime](#making-sure-your-tpm-is-ready-for-keylime)\n* [Usage](#usage)\n  * [Configuring keylime](#configuring-keylime)\n  * [Running keylime](#running-keylime)\n  * [Provisioning](#provisioning)\n  * [Using keylime CA](#using-keylime-ca)\n* [Request a Feature](#request-a-feature)\n* [Security Vulnerability Management Policy](#security-vulnerability-management-policy)\n* [Meeting Information](#project-meetings)\n* [Contributing: First Timers Support](#contributing--first-timers-support)\n* [Testing](#testing)\n* [Additional Reading](#additional-reading)\n* [Disclaimer](#disclaimer)\n\n## Installation\n\n### Automated\n\n#### Using installer script\n\nKeylimes installer requires Python 3.6 or greater.\n\nThe following command line options are available using \n[installer.sh](https://github.com/keylime/keylime/blob/master/installer.sh) script:\n\n```\nUsage: ./installer.sh [option...]\nOptions:\n-k              Download Keylime (stub installer mode)\n-m              Use modern TPM 2.0 libraries (vs. TPM 1.2)\n-s              Install \u0026 use a Software TPM emulator (development only)\n-p PATH         Use PATH as Keylime path\n-h              This help info\n```\n\nShould you not have the Keylime repository on your local machine, you can\nuse the `-k` flag which will download the software. In this case, all you need\nis the `installer.sh` script locally.\n\n#### Installer Distribution coverage\n\n| Distribution  | Versions      | TPM2-Software   |\n| ------------- |:-------------:| -----:          |\n| CentOS        | 7 / 8         | Compiled        |\n| RHEL          | 7 / 8         | Compiled        |\n| Fedora        | 32 / 33 / 34  | Package Install |\n| Ubuntu        | 19 LTS / 20   | Compiled        |\n\n#### Ansible\n\nAnsible roles are available to deploy keylime for use with a hardware TPM or a software TPM emulator. \nPlease proceed to the [Keylime Ansible\nRepository](https://github.com/keylime/ansible-keylime).\nOr, alternatively the [Keylime Ansible TPM Emulator\nRepository](https://github.com/keylime/ansible-keylime-tpm-emulator).\n\n| WARNING: The \"Keylime Ansible TPM Emulator\" role uses a software TPM, which is considered cryptographically insecure. It should only be used for development or testing and **NOT** in production!|\n| --- |\n\n\n#### Docker (Production)\nThe verifier, registrar and tenant can be deployed using Docker images.\nKeylime's official images can be found [here](https://quay.io/organization/keylime).\nThose are automatically generated for every commit and release.\n\nFor building those images locally see \n[here](https://github.com/keylime/keylime/blob/master/docker/release/build_locally.sh\u003e).\n\n#### Docker (Development)\n\nKeylime and related emulators can also be run using Docker for development.\nSince this Docker configuration currently uses a TPM emulator,\nit should only be used for development or testing and NOT in production.\n\nPlease see either the \n[Dockerfiles](https://github.com/keylime/keylime/tree/master/docker) or our\n[local CI script](https://github.com/keylime/keylime/blob/master/.ci/run_local.sh)\nwhich will automate the build and pull of Keylime.\n\n### Manual\n\nKeylimes installer requires Python 3.6 or greater.\n\n#### Python-based prerequisites\n\nThe list of Python packages needed to install keylime can be found in\n [requirements.txt](https://github.com/keylime/keylime/tree/master/requirements.txt).\n\nSome of them are usually available as distro packages.\nSee [installer.sh](https://github.com/keylime/keylime/blob/master/installer.sh)\n for more information, if you want to install them this way.\n\nYou can also install them using pip:\n\n```bash\npython3 -m pip install -r requirements.txt\n```\n\n#### TPM utility prerequisites\n\nKeylime uses the Intel TPM2 software set to provide TPM 2.0 support.\n\nThese can be installed using your package manager.\n\n* On Fedora 32 (and greater):\n\n`sudo dnf install tpm2-tss tpm2-tools`\n\n* On Ubuntu 20 LTS (and greater):\n\n`sudo apt-get install tpm2-tools`\n\nYou can also build the [tpm2-tss](https://github.com/tpm2-software/tpm2-tss) software stack as well as\n[tpm2-tools](https://github.com/tpm2-software/tpm2-tools) instead . See the\nREADME.md in these projects for detailed instructions on how to build and install.\n\nTo ensure that you have the supported version installed ensure that you have\nthe `tpm2_checkquote` utility in your path.\n\n###### TPM 2.0 Access\n\nThe Linux kernel provides a resource manager since version 5.4 which is \nconfigured as the default in Keylime. On older kernel versions it is \nrecommended to use the [tpm2-abrmd](https://github.com/tpm2-software/tpm2-abrmd) \nresource manager.\n\nAlternatively, it is also possible, though not recommended, to communicate\ndirectly with the TPM (and not use a resource manager).  This can be done by\nsetting the environment var `TPM2TOOLS_TCTI` to the appropriate value:\n\nTo talk directly to the swtpm2 emulator: \n\n`export TPM2TOOLS_TCTI=\"mssim:port=2321\"`\n\nTo talk directly to a real TPM: \n\n`export TPM2TOOLS_TCTI=\"device:/dev/tpm0\"`\n\n#### Install Keylime\n\nYou're finally ready to install keylime!\n\n```bash\nsudo python3 -m pip install . -r requirements.txt\n```\n\n## Making sure your TPM is ready for keylime\n\nThe above instructions for installing the TPM libraries will be configured\nto talk to `/dev/tpm0`.  If this device is not on your system, then you may need\nto build/install TPM support for your kernel.  You can use following command\nto see if the kernel is initializing the TPM driver during boot:\n\n`dmesg | grep -i tpm`\n\nIf you have the `/dev/tpm0` device, you next need to get it into the right state. The kernel\ndriver reports status on the TPM in `/sys`.  You can locate the folder with relevant\ninfo from the driver using:\n\n`sudo find /sys -name tpm0`\n\nSeveral results may be returned, but the duplicates are just symlinks to one\nlocation.  Go to one of the returned paths, for example, `/sys/class/misc/tpm0`.  Now\nchange to the device directory.  Here you can find some information from the TPM like\nthe current pcr values and sometimes the public EK is available.  It will also report\ntwo important state values: active and enabled.  To use keylime, both of these must\nbe 1.  If they are not, you may need to reboot into the BIOS to enable and activate\nthe TPM.  If you need to both enable and activate, then you must enable first, reboot,\nthen activate and finally reboot again.  It is also possible that you may need to\nassert physical presence (see manual for your system on how to do this) in order to\naccomplish these actions in your BIOS.\n\nIf your system shows enabled and active, you can next check the \"owned\" status\nin the /sys directory. The [sysfs ABI](https://www.kernel.org/doc/Documentation/ABI/stable/sysfs-class-tpm) lists\nwhere the kernel populates these entries. Keylime can take a system that is not\nowned (i.e., owned = 0) and take control of it.  Keylime can also take a system\nthat is already owned, provided that you know the owner password and that\nkeylime or another trusted computing system that relies upon tpm4720 previously\ntook ownership.  If you know the owner password, you can set the option\n`tpm_ownerpassword` in `keylime.conf` to this known value.\n\n## Usage\n\n### Configuring keylime\n\nkeylime puts its configuration in `/etc/keylime.conf`.  It will also take an alternate\nlocation for the config in the environment var `KEYLIME_CONFIG`.\n\nThis file is documented with comments and should be self-explanatory.\n\n### Running keylime\n\nKeylime has three major component services that run: the registrar, verifier, and the agent:\n\n* The *registrar* is a simple HTTPS service that accepts TPM public keys.  It then\npresents an interface to obtain these public keys for checking quotes.\n\n* The *verifier* is the most important component in keylime.  It does initial and\nperiodic checks of system integrity and supports bootstrapping a cryptographic key\nsecurely with the agent.  The verifier uses mutual TLS for its control interface.\n\n    By default, the verifier will create appropriate TLS certificates for itself\n    in `/var/lib/keylime/cv_ca/`.  The registrar and tenant will use this as well.  If\n    you use the generated TLS certificates then all the processes need to run as root\n    to allow reading of private key files in `/var/lib/keylime/`.\n\n* The *agent* is the target of bootstrapping and integrity measurements.  It puts\n    its stuff into `/var/lib/keylime/`.\n\nIf you are using the TPM emulator make sure that `TPM2TOOLS_TCTI` is correctly set with: \n`export TPM2TOOLS_TCTI=\"mssim:port=2321\"`.\nTo run a basic test, run `keylime_verifier`, `keylime_registrar`, and `keylime_agent`.  If\nthe agent starts up properly, then you can proceed.\n\n### Provisioning\n\nTo kick everything off you need to tell keylime to provision a machine. This can be\ndone with the keylime tenant.\n\n#### Provisioning with keylime_tenant\n\nThe `keylime_tenant` utility can be used to provision your agent.\n\nAs an example, the following command tells keylime to provision a new agent\nat 127.0.0.1 with UUID d432fbb3-d2f1-4a97-9ef7-75bd81c00000 and talk to a\nverifier at 127.0.0.1.  Finally it will encrypt a file called `filetosend`\nand send it to the agent allowing it to decrypt it only if the configured TPM\npolicy (in `/etc/keylime.conf`) is satisfied:\n\n`keylime_tenant -c add -t 127.0.0.1 -v 127.0.0.1 -u D432fbb3-d2f1-4a97-9ef7-75bd81c00000 -f filetosend`\n\nTo stop keylime from requesting attestations:\n\n`keylime_tenant -c delete -t 127.0.0.1 -u d432fbb3-d2f1-4a97-9ef7-75bd81c00000`\n\nFor additional advanced options for the tenant utility run:\n\n`keylime_tenant -h`\n\n### Using keylime CA\n\nA simple certificate authority is available to use with keylime. You can interact\nwith it using `keylime_ca` or `keylime_tenant`.  Options for configuring the\ncertificates that `keylime_ca` creates are in `/etc/keylime.conf`.\n\nNOTE: This CA functionality is different than the TLS support for talking to\nthe verifier or registrar (though it uses some of the same config options\nin `/etc/keylime.conf`).  This CA is for the Keylime Agents you provision and\nyou can use keylime to bootstrap the private keys into agents.\n\nTo initialize a new certificate authority run:\n\n`keylime_ca --command init`\n\nThis will create a certificate authority in `/var/lib/keylime/ca` and requires\nroot access to write to the directory.  Use `-d` to point it to another directory\nnot necessarily requiring root.\n\nYou can create certificates under this ca using:\n\n`keylime_ca --command create --name certname.host.com`\n\nThis will create a certificate signed by the CA in `/var/lib/keylime/ca` (`-d` also\nworks here to have it use a different CA directory).\n\nTo obtain a zip file of the certificate, public key, and private key for a cert use:\n\n`keylime_ca --command pkg --name certname.host.com`\n\nThis will zip the above files and place them in /var/lib/keylime/ca/certname.host.com-pkg.zip.  The\nprivate key will be protected by the key that you were prompted with.\n\nYou may wonder why this is in keylime at all?  Well, you can tell `keylime_tenant` to\nautomatically create a key and then provision an agent with it.  Use the --cert\noption in `keylime_tenant` to do this.  This takes in the directory of the CA:\n\n`keylime_tenant -c add -t 127.0.0.1 -u d432fbb3-d2f1-4a97-9ef7-75bd81c00000 --cert /var/lib/keylime/ca`\n\nIf you also have the option extract_payload_zip in `/etc/keylime.conf` set to `True` on\nthe keylime agent, then it will automatically extract the zip containing an unprotected\nprivate key, public key, certificate and CA certificate to `/var/lib/keylime/secure/unzipped`.\n\nIf the keylime verifier option `revocation_notifier` is set to `True`, then\nthe CV will sign a revocation message and send it over 0mq to any subscribers.  The\nkeylime CA supports listening to these notifications and will generate an updated\nCRL.  To enable this feature, run:\n\n`keylime_ca -c listen`\n\nThe revocation key will be automatically created by the tenant the first time\nyou use the CA with keylime.  Currently the CRL is only written back to the CA\ndirectory.\n\n## Systemd service support\n\nThe directory `services/` includes `systemd` service files for the verifier,\nagent and registrar.\n\nYou can install the services with the following command:\n\n`sudo ./services/install.sh`\n\nOnce installed, you can run and inspect the services `keylime_verifier`,\n`keylime_agent` and `keylime_registrar` via `systemctl`.\n\n### Request a feature\n\nKeylime feature requests are tracked as enhancements in the [enhancements repository](https://github.com/keylime/enhancements)\n\nThe enhancement process has been implemented to provide a way to review and\nassess the impact(s) of significant changes to Keylime.\n\n## Security Vulnerability Management Policy\n\nIf you would have found a security vulnerability in Keylime and would like to\nreport, first of all: thank you.\n\nPlease contact us directly at [security@keylime.groups.io](mailto:security@keylime.groups.io)\nfor any bug that might impact the security of this project. **Do not** use a\nGithub issue to report any potential security bugs.\n\n\n## Project Meetings\n\nWe meet every Wednesday @ 15:00 UTC to 15:30. Anyone is welcome to join the meeting.\n\nThe meeting is hosted in [CNCF chat (Slack)](https://cloud-native.slack.com/archives/C01ARE2QUTZ)\n\nMeeting agenda are hosted and archived in the [meetings repo](https://github.com/keylime/meetings) as Github issues.\n\n## Contributing: First Timers Support\n\nWe welcome new contributors to Keylime of any form, including those of you who maybe new to working in an open source project.\n\nSo if you are new to open source development, don't worry, there are a myriad of ways you can get involved in our open source project. As a start, try exploring issues with [`good first issue`](https://github.com/keylime/keylime/labels/good%20first%20issue) label.\nWe understand that the process of creating a Pull Request (PR) can be a barrier for new contributors. These issues are reserved for new contributors like you. If you need any help or advice in making the PR, feel free to jump into our [chat room](https://cloud-native.slack.com/archives/C01ARE2QUTZ) and ask for help there.\n\nYour contribution is our gift to make our project even more robust. Check out [CONTRIBUTING.md](https://github.com/keylime/keylime/blob/master/CONTRIBUTING.md) to find out more about how to contribute to our project.\n\nKeylime uses [Semantic Versioning](https://semver.org/). It is recommended you also read the [RELEASE.md](RELEASE.md)\nfile to learn more about it and familiarise yourself with simple of examples of using it.\n\n## Testing\n\nPlease, see [TESTING.md](TESTING.md) for details.\n\n## Additional Reading\n\n* Executive summary Keylime slides: [docs/old/keylime-elevator-slides.pptx](https://github.com/keylime/keylime/raw/master/docs/old/keylime-elevator-slides.pptx)\n* Detailed Keylime Architecture slides: [docs/old/keylime-detailed-architecture-v7.pptx](https://github.com/keylime/keylime/raw/master/docs/old/keylime-detailed-architecture-v7.pptx)\n* See ACSAC 2016 paper in doc directory: [docs/old/tci-acm.pdf](https://github.com/keylime/keylime/blob/master/docs/old/tci-acm.pdf)\n  * and the ACSAC presentation on keylime: [docs/old/llsrc-keylime-acsac-v6.pptx](https://github.com/keylime/keylime/raw/master/docs/old/llsrc-keylime-acsac-v6.pptx)\n* See the HotCloud 2018 paper: [docs/old/hotcloud18.pdf](https://github.com/keylime/keylime/blob/master/docs/old/hotcloud18.pdf)\n* Details about Keylime REST API: [docs/old/keylime RESTful API.docx](https://github.com/keylime/keylime/raw/master/docs/old/keylime%20RESTful%20API.docx)\n* [Demo files](demo/) - Some pre-packaged demos to show off what Keylime can do.\n* [IMA stub service](ima_stub_service/) - Allows you to test IMA and keylime on a machine without a TPM.  Service keeps emulated TPM synchronized with IMA.\n\n#### Errata from the ACSAC Paper\n\nWe discovered a typo in Figure 5 of the published ACSAC paper. The final interaction\nbetween the Tenant and Cloud Verifier showed an HMAC of the node's ID using the key\nK_e.  This should be using K_b. The paper in this repository and the ACSAC presentation\nhave been updated to correct this typo.\n\nThe software that runs on the system with the TPM is now called the keylime *agent* rather\nthan the *node*.  We have made this change in the documentation and code.  The ACSAC paper\nwill remain as it was published using *node*.\n\n## Disclaimer\n\nDISTRIBUTION STATEMENT A. Approved for public release: distribution unlimited.\n\nThis material is based upon work supported by the Assistant Secretary of Defense for\nResearch and Engineering under Air Force Contract No. FA8721-05-C-0002 and/or\nFA8702-15-D-0001. Any opinions, findings, conclusions or recommendations expressed in this\nmaterial are those of the author(s) and do not necessarily reflect the views of the\nAssistant Secretary of Defense for Research and Engineering.\n\nKeylime's license was changed from BSD Clause-2 to Apache 2.0. The original BSD\nClause-2 licensed code can be found on the [MIT github\norganization](https://github.com/mit-ll/MIT-keylime).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstringlytyped%2Fkeylime","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstringlytyped%2Fkeylime","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstringlytyped%2Fkeylime/lists"}