Package: keylime
Note: Keylime Python modules do not have a stable API and might change without notice!KeylimeKeylime is an open-source scalable trust system harnessing TPM Technology.Keylime provides an end-to-end solution for bootstrapping hardware rooted
cryptographic trust for remote machines, the provisioning of encrypted payloads,
and run-time system integrity monitoring. It also provides a flexible
framework for the remote attestation of any givenPCR(Platform Configuration
Register). Users can create their own customized actions that will trigger when
a machine fails its attested measurements.Keylime's mission is to make TPM Technology easily accessible to developers and
users alike, without the need for a deep understanding of the lower levels of a
TPM's operations. Amongst many scenarios, it well suited to tenants who need to
remotely attest machines not under their own full control (such as a consumer of
hybrid cloud or a remote Edge / IoT device in an insecure physical tamper prone
location.)Keylime can be driven with a CLI application and a set of RESTful APIs.Keylime consists of three main components; The Verifier, Registrar and the
Agent.The Verifier continuously verifies the integrity state of the machine that
the agent is running on.The Registrar is a database of all agents registered
with Keylime and hosts the public keys of the TPM vendors.The Agent is deployed to the remote machine that is to be measured or provisioned
with secrets stored within an encrypted payload released once trust is established.Rust based Keylime AgentThe verifier, registrar, and agent are all developed in Python and situated
in this repositorykeylime. The agent was ported to theRust programming language. The code can be found
in therust-keylime repository.The decision was made to port the agent to Rust, as rust is a low-level
performant systems language designed with security as a central tenet, by means
of the rust compiler's ownership model.Starting with the 0.1.0 release of the Rust based Keylime agent, this agent is now the official agent.IMPORTANT: The Python version is deprecated and will be removed with the next major version (7.0.0)!TPM SupportKeylime supports TPM version2.0.Keylime can be used with a hardware TPM, or a software TPM emulator for
development, testing, or demonstration purposes.  However, DO NOT USE Keylime in
production with a TPM emulator!  A software TPM emulator does not provide a
hardware root of trust and dramatically lowers the security benefits of using
Keylime.A hardware TPM should always be used when real secrets and trust is required.Table of ContentsInstallationUsageConfiguring KeylimeRunning KeylimeProvisioningRequest a FeatureSecurity Vulnerability Management PolicyMeeting InformationContributing: First Timers SupportTestingAdditional ReadingDisclaimerInstallationTo install Keylime refer tothe instructions found in the documentation.UsageConfiguring KeylimeKeylime puts its configuration in/etc/keylime/*.confor/usr/etc/keylime/*.conf.
It will also take an alternate location for the config in the environment varkeylime_{VERIFIER,REGISTRAR,TENANT,CA,LOGGING}_CONFIG.Those files are documented with comments and should be self-explanatory in most cases.Running KeylimeKeylime has three major component services that run: the registrar, verifier, and the agent:Theregistraris a simple HTTPS service that accepts TPM public keys.  It then
presents an interface to obtain these public keys for checking quotes.Theverifieris the most important component in Keylime.  It does initial and
periodic checks of system integrity and supports bootstrapping a cryptographic key
securely with the agent.  The verifier uses mutual TLS for its control interface.By default, the verifier will create appropriate TLS certificates for itself
in/var/lib/keylime/cv_ca/.  The registrar and tenant will use this as well.  If
you use the generated TLS certificates then all the processes need to run as root
to allow reading of private key files in/var/lib/keylime/.Theagentis the target of bootstrapping and integrity measurements.  It puts
its stuff into/var/lib/keylime/.ProvisioningTo kick everything off you need to tell Keylime to provision a machine. This can be
done with the Keylime tenant.Provisioning with keylime_tenantThekeylime_tenantutility can be used to provision your agent.As an example, the following command tells Keylime to provision a new agent
at 127.0.0.1 with UUID d432fbb3-d2f1-4a97-9ef7-75bd81c00000 and talk to a
verifier at 127.0.0.1. Finally, it will encrypt a file calledfiletosendand send it to the agent allowing it to decrypt it only if the configured TPM
policy is satisfied:keylime_tenant -c add -t 127.0.0.1 -v 127.0.0.1 -u D432fbb3-d2f1-4a97-9ef7-75bd81c00000 -f filetosendTo stop Keylime from requesting attestations:keylime_tenant -c delete -t 127.0.0.1 -u d432fbb3-d2f1-4a97-9ef7-75bd81c00000For additional advanced options for the tenant utility run:keylime_tenant -hDocumentation on how to create runtime and measured boot policies can be found in
theKeylime User Guide.Systemd service supportThe directoryservices/includessystemdservice files for the verifier,
agent and registrar.You can install the services with the following command:sudo ./services/installer.shOnce installed, you can run and inspect the serviceskeylime_verifierandkeylime_registrarviasystemctl.
The Rust agent repository also contains a systemd service file for the agent.Request a featureKeylime feature requests are tracked as enhancements in theenhancements repositoryThe enhancement process has been implemented to provide a way to review and
assess the impact(s) of significant changes to Keylime.Security Vulnerability Management PolicyIf you have found a security vulnerability in Keylime and would like to
report, first of all: thank you.Please contact us directly atsecurity@keylime.groups.iofor any bug that might impact the security of this project.Do notuse a
Github issue to report any potential security bugs.Project MeetingsWe meet on the fourth Wednesday each month @ 15:30 GMT to 16:30. Anyone is welcome to join the meeting.The meeting is normally announced onCNCF chat (Slack)Meeting agenda are hosted and archived in themeetings repoas GitHub issues.Contributing: First Timers SupportWe welcome new contributors to Keylime of any form, including those of you who maybe new to working in an open source project.So 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 withgood first issuelabel.
We 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 ourchat roomand ask for help there.Your contribution is our gift to make our project even more robust. Check outCONTRIBUTING.mdto find out more about how to contribute to our project.Keylime usesSemantic Versioning. It is recommended you also read theRELEASE.mdfile to learn more about it and familiarise yourself with simple of examples of using it.TestingPlease, seeTESTING.mdfor details.Additional ReadingExecutive summary Keylime slides:docs/old/keylime-elevator-slides.pptxDetailed Keylime Architecture slides:docs/old/keylime-detailed-architecture-v7.pptxSee ACSAC 2016 paper in doc directory:docs/old/tci-acm.pdfand the ACSAC presentation on Keylime:docs/old/llsrc-keylime-acsac-v6.pptxSee the HotCloud 2018 paper:docs/old/hotcloud18.pdfDetails about Keylime REST API:docs/old/keylime RESTful API.docxDemo files- Some pre-packaged demos to show off what Keylime can do.IMA stub service- Allows you to test IMA and Keylime on a machine without a TPM.  Service keeps emulated TPM synchronized with IMA.Errata from the ACSAC PaperWe discovered a typo in Figure 5 of the published ACSAC paper. The final interaction
between the Tenant and Cloud Verifier showed an HMAC of the node's ID using the key
K_e.  This should be using K_b. The paper in this repository and the ACSAC presentation
have been updated to correct this typo.The software that runs on the system with the TPM is now called the Keylimeagentrather
than thenode.  We have made this change in the documentation and code.  The ACSAC paper
will remain as it was published usingnode.DisclaimerDISTRIBUTION STATEMENT A. Approved for public release: distribution unlimited.This material is based upon work supported by the Assistant Secretary of Defense for
Research and Engineering under Air Force Contract No. FA8721-05-C-0002 and/or
FA8702-15-D-0001. Any opinions, findings, conclusions or recommendations expressed in this
material are those of the author(s) and do not necessarily reflect the views of the
Assistant Secretary of Defense for Research and Engineering.Keylime's license was changed from BSD Clause-2 to Apache 2.0. The original BSD
Clause-2 licensed code can be found on theMIT GitHub
organization.