注意：Keylime Python 模块没有稳定的 API，可能会更改，恕不另行通知！

酸橙

Keylime 是一个利用 TPM 技术的开源可扩展信任系统。

Keylime 提供了一个端到端的解决方案，用于引导远程机器的硬件根加密信任、加密有效负载的配置以及运行时系统完整性监控。它还为任何给定PCR（平台配置寄存器）的远程证明提供了一个灵活的框架。用户可以创建自己的自定义操作，这些操作将在机器未能通过其认证测量时触发。

Keylime 的使命是让开发人员和用户都可以轻松访问 TPM 技术，而无需深入了解 TPM 操作的较低级别。在许多场景中，它非常适合需要远程证明不受自己完全控制的机器的租户（例如混合云的消费者或位于不安全的物理易篡改位置的远程边缘/物联网设备。）

Keylime 可以使用 CLI 应用程序和一组 RESTful API 来驱动。

Keylime 由三​​个主要部分组成；验证者、注册者和代理。

• 验证程序不断验证代理运行所在机器的完整性状态。

• Registrar 是在 Keylime 注册的所有代理的数据库，并托管 TPM 供应商的公钥。

• 代理被部署到远程机器上，一旦建立信任，将使用存储在加密有效负载中的秘密进行测量或配置。

基于 Rust 的 Keylime 代理

验证者、注册者和代理都使用 Python 开发并位于此存储库keylime中。该代理目前正在移植到 Rust 编程语言，这项工作在rust-keylime 存储库中进行。

决定将代理移植到 Rust，因为 rust 是一种低级高性能系统语言，通过 rust 编译器的所有权模型设计以安全为中心原则。

防锈剂工作完成后，rust-keylime 代理将成为 Keylime 中推荐的持续代理。在此之前，Python 代理功能完全正常，可用作远程监控系统，与 keylime 验证器和注册器进行交互。

TPM 支持

Keylime 支持 TPM 2.0 版。

Keylime 可以与硬件 TPM 或软件 TPM 仿真器一起用于开发、测试或演示目的。但是，不要在生产环境中使用带有 TPM 仿真器的 keylime！软件 TPM 仿真器不提供硬件信任根，并显着降低使用 keylime 的安全优势。

当需要真正的机密和信任时，应始终使用硬件 TPM。

目录

• 安装
  • 自动化
  • 手动的
• 确保您的 TPM 已为 keylime 做好准备
• 用法
  • 配置 keylime
  • 运行关键石灰
  • 供应
  • 使用 keylime CA
• 请求功能
• 安全漏洞管理策略
• 会议信息
• 贡献：初学者支持
• 测试
• 附加阅读
• 免责声明

安装

自动化

使用安装程序脚本

Keylimes 安装程序需要 Python 3.6 或更高版本。

使用installer.sh脚本可以使用以下命令行选项 ：

Usage: ./installer.sh [option...]
Options:
-k              Download Keylime (stub installer mode)
-t              Create tarball with keylime_agent
-m              Use modern TPM 2.0 libraries (vs. TPM 1.2)
-s              Install & use a Software TPM emulator (development only)
-p PATH         Use PATH as Keylime path
-h              This help info

如果您的本地计算机上没有 Keylime 存储库，您可以使用-k将下载该软件的标志。在这种情况下，您只需要installer.sh本地脚本。

安装程序分布范围

Ansible

Ansible 角色可用于部署用于硬件 TPM 或软件 TPM 模拟器的 keylime。请继续访问Keylime Ansible 存储库。或者，或者Keylime Ansible TPM Emulator Repository。

Docker（仅限开发）

也可以使用 Docker 部署 keylime 和相关的模拟器。由于此 docker 配置当前使用 TPM 模拟器，因此它只能用于开发或测试，而不应用于生产。

请查看 Dockerfiles或我们的 本地 CI 脚本 ，它们将自动构建和提取 keylime。

手动的

Keylimes 安装程序需要 Python 3.6 或更高版本。

基于 Python 的先决条件

安装 keylime 所需的 Python 包列表可以在 requirements.txt中找到。

其中一些通常作为发行包提供。 如果您想以这种方式安装它们，请参阅installer.sh了解更多信息。

您也可以使用 pip 安装它们：

python3 -m pip install -r requirements.txt

TPM 实用程序先决条件

Keylime 使用 Intel TPM2 软件集提供 TPM 2.0 支持。

这些可以使用您的包管理器安装。

• 在 Fedora 32（及更高版本）上：

sudo dnf install tpm2-tss tpm2-tools

• 在 Ubuntu 20 LTS（及更高版本）上：

sudo apt-get install tpm2-tools

您还可以构建tpm2-tss软件堆栈以及 tpm2-tools代替。有关如何构建和安装的详细说明，请参阅这些项目中的 README.md。

为确保您安装了受支持的版本，请确保tpm2_checkquote您的路径中有该实用程序。

TPM 2.0 访问

Linux 内核从 5.4 版开始提供了一个资源管理器，它在 Keylime 中被配置为默认值。在较旧的内核版本上，建议使用tpm2-abrmd 资源管理器。

或者，虽然不推荐，但也可以直接与 TPM 通信（而不使用资源管理器）。这可以通过将环境变量设置TPM2TOOLS_TCTI为适当的值来完成：

直接与 swtpm2 仿真器对话：

export TPM2TOOLS_TCTI="mssim:port=2321"

直接与真正的 TPM 对话：

export TPM2TOOLS_TCTI="device:/dev/tpm0"

安装 Keylime

您终于可以安装 keylime 了！

sudo python3 -m pip install . -r requirements.txt

确保您的 TPM 已为 keylime 做好准备

上述安装 TPM 库的说明将配置为与/dev/tpm0. 如果此设备不在您的系统上，那么您可能需要为您的内核构建/安装 TPM 支持。您可以使用以下命令查看内核在引导期间是否正在初始化 TPM 驱动程序：

dmesg | grep -i tpm

如果您拥有该/dev/tpm0设备，接下来需要将其置于正确的状态。内核驱动程序在/sys. 您可以使用以下方法从驱动程序中找到包含相关信息的文件夹：

sudo find /sys -name tpm0

可能会返回多个结果，但重复项只是指向一个位置的符号链接。转到返回的路径之一，例如/sys/class/misc/tpm0. 现在切换到设备目录。在这里，您可以找到来自 TPM 的一些信息，例如当前 pcr 值，有时还可以使用公共 EK。它还将报告两个重要的状态值：活动和启用。要使用 keylime，这两个都必须为 1。如果不是，您可能需要重新启动进入 BIOS 以启用和激活 TPM。如果您需要启用和激活，则必须先启用，重新启动，然后激活，最后再次重新启动。为了在 BIOS 中完成这些操作，您也可能需要断言物理存在（请参阅系统手册了解如何执行此操作）。

如果您的系统显示已启用且处于活动状态，您接下来可以检查 /sys 目录中的“拥有”状态。sysfs ABI列出了内核填充这些条目的位置。Keylime 可以采用不属于自己的系统（即，拥有 = 0）并控制它。Keylime 也可以获取已经拥有的系统，前提是您知道所有者密码并且之前依赖于 tpm4720 的 keylime 或其他受信任的计算系统获得了所有权。如果您知道所有者密码，则可以将选项设置 tpm_ownerpassword为此keylime.conf已知值。

用法

配置 keylime

keylime 将其配置放入/etc/keylime.conf. 它还将为环境 var 中的配置提供一个备用位置KEYLIME_CONFIG。

该文件带有注释，应该是不言自明的。

运行关键石灰

Keylime 运行三个主要的组件服务：注册器、验证器和代理：

• 注册器是一个简单的HTTPS 服务，它接受 TPM 公钥。然后它会提供一个接口来获取这些用于检查报价的公钥。

• 验证者是 keylime 中最重要的组件。它对系统完整性进行初始和定期检查，并支持使用代理安全地引导加密密钥。验证者使用双向 TLS 作为其控制接口。

  默认情况下，验证者会在/var/lib/keylime/cv_ca/. 注册商和租户也将使用它。如果您使用生成的 TLS 证书，则所有进程都需要以 root 身份运行，以允许读取/var/lib/keylime/.

• 代理是引导和完整性测量的目标。它把它的东西放进去/var/lib/keylime/。

如果您使用的是 TPM 模拟器，请确保TPM2TOOLS_TCTI正确设置为： export TPM2TOOLS_TCTI="mssim:port=2321"。要运行基本测试，请运行keylime_verifier、keylime_registrar和keylime_agent。如果代理正确启动，那么您可以继续。

供应

要开始一切，您需要告诉 keylime 配置机器。这可以通过 keylime 租户来完成。

使用 keylime_tenant 进行配置

该keylime_tenant实用程序可用于配置您的代理。

例如，以下命令告诉 keylime 在 127.0.0.1 使用 UUID d432fbb3-d2f1-4a97-9ef7-75bd81c00000 配置一个新代理，并与 127.0.0.1 的验证者对话。最后，它将加密一个名为的文件filetosend 并将其发送给代理，仅当满足配置的 TPM 策略 (in) 时才允许它解密/etc/keylime.conf：

keylime_tenant -c add -t 127.0.0.1 -v 127.0.0.1 -u D432fbb3-d2f1-4a97-9ef7-75bd81c00000 -f filetosend

要阻止 keylime 请求证明：

keylime_tenant -c delete -t 127.0.0.1 -u d432fbb3-d2f1-4a97-9ef7-75bd81c00000

有关租户实用程序的其他高级选项，请运行：

keylime_tenant -h

使用 keylime CA

一个简单的证书颁发机构可用于 keylime。您可以使用keylime_ca或与它进行交互keylime_tenant。用于配置keylime_ca创建的证书的选项位于/etc/keylime.conf.

注意：此 CA 功能不同于与验证者或注册者对话的 TLS 支持（尽管它使用 中的一些相同配置选项/etc/keylime.conf）。此 CA 用于您配置的 Keylime 代理，您可以使用 keylime 将私钥引导到代理中。

要初始化新的证书颁发机构，请运行：

keylime_ca --command init

这将在其中创建一个证书颁发机构，/var/lib/keylime/ca并且需要 root 访问权限才能写入该目录。用于-d将其指向另一个不一定需要 root 的目录。

您可以使用以下方法在此 ca 下创建证书：

keylime_ca --command create --name certname.host.com

这将创建一个由 CA 签名的证书/var/lib/keylime/ca（-d也可以在这里使用不同的 CA 目录）。

要获取证书、公钥和私钥的 zip 文件以用于证书，请使用：

keylime_ca --command pkg --name certname.host.com

这将压缩上述文件并将它们放在 /var/lib/keylime/ca/certname.host.com-pkg.zip 中。私钥将受到提示您使用的密钥的保护。

您可能想知道为什么这是在 keylime 中？好吧，您可以告诉keylime_tenant自动创建一个密钥，然后用它来配置代理。使用 --cert 选项keylime_tenant来执行此操作。这需要 CA 的目录：

keylime_tenant -c add -t 127.0.0.1 -u d432fbb3-d2f1-4a97-9ef7-75bd81c00000 --cert /var/lib/keylime/ca

如果您还在keylime 代理上/etc/keylime.conf设置了选项 extract_payload_zip True，那么它会自动将包含未受保护的私钥、公钥、证书和 CA 证书的 zip 提取到/var/lib/keylime/secure/unzipped.

如果 keylime 验证器选项revocation_notifier设置为True，则 CV 将签署撤销消息并通过 0mq 将其发送给任何订阅者。keylime CA 支持侦听这些通知并将生成更新的 CRL。要启用此功能，请运行：

keylime_ca -c listen

当您首次将 CA 与 keylime 一起使用时，租户将自动创建吊销密钥。目前 CRL 只写回 CA 目录，除非正在使用 IPsec 配置（请参阅附加阅读）。

系统服务支持

该目录services/包括systemd验证者、代理和注册商的服务文件。

您可以使用以下命令安装服务：

sudo ./services/install.sh

安装后，您可以运行和检查服务keylime_verifier， keylime_agent并keylime_registrar通过systemctl.

请求功能

Keylime 功能请求作为增强存储库中的增强进行跟踪

已实施增强过程，以提供一种方法来审查和评估对 Keylime 的重大更改的影响。

安全漏洞管理策略

如果您在 Keylime 中发现了安全漏洞并想报告，首先：谢谢。

请通过security@keylime.groups.io直接与我们联系，以 了解任何可能影响该项目安全性的错误。不要使用 Github 问题报告任何潜在的安全漏洞。

项目会议

我们每周三 @ 15:00 UTC 到 15:30 见面。欢迎任何人加入会议。

会议在CNCF 聊天 (Slack)中主持

会议议程作为 Github 问题托管并存档在会议存储库中。

贡献：初学者支持

我们欢迎任何形式的 Keylime 新贡献者，包括那些可能刚接触开源项目的人。

因此，如果您是开源开发的新手，请不要担心，您可以通过多种方式参与我们的开源项目。首先，尝试探索good first issue标签问题。我们了解创建拉取请求 (PR) 的过程可能会成为新贡献者的障碍。这些问题是为像您这样的新贡献者保留的。如果您在制作 PR 时需要任何帮助或建议，请随时跳入我们的聊天室并在那里寻求帮助。

您的贡献是我们的礼物，使我们的项目更加强大。查看CONTRIBUTING.md以了解有关如何为我们的项目做出贡献的更多信息。

Keylime 使用语义版本控制。建议您也阅读RELEASE.md 文件以了解更多信息并熟悉使用它的简单示例。

测试

请参阅TESTING.md了解详细信息。

附加阅读

• 执行摘要 Keylime 幻灯片：docs/old/keylime-elevator-slides.pptx
• 详细的 Keylime 架构幻灯片：docs/old/keylime-detailed-architecture-v7.pptx
• 请参阅文档目录中的 ACSAC 2016 论文：docs/old/tci-acm.pdf
  • 以及关于 keylime 的 ACSAC 演示文稿：docs/old/llsrc-keylime-acsac-v6.pptx
• 请参阅 HotCloud 2018 论文：docs/old/hotcloud18.pdf
• 关于 Keylime REST API 的详细信息：docs/old/keylime RESTful API.docx
• 捆绑便携式云代理- 创建云代理的便携式压缩包，用于没有 python 和其他依赖项的系统。
• IPsec 配置
  • IPsec with Libreswan - 使用 Libreswan 后端配置 Keylime 以实现 IPsec 功能。
  • IPsec with Racoon - 使用 Racoon 后端配置 Keylime 以实现 IPsec 功能。
• 演示文件- 一些预先打包的演示以展示 Keylime 的功能。
• IMA 存根服务- 允许您在没有 TPM 的机器上测试 IMA 和 keylime。服务使模拟的 TPM 与 IMA 保持同步。

ACSAC 论文中的勘误表

我们在已发表的 ACSAC 论文的图 5 中发现了一个错字。租户和云验证者之间的最终交互显示了使用密钥 K_e 的节点 ID 的 HMAC。这应该使用 K_b。此存储库中的论文和 ACSAC 演示文稿已更新以更正此错字。

使用 TPM 在系统上运行的软件现在称为 keylime代理而不是节点。我们已在文档和代码中进行了此更改。ACSAC 论文将保持原样使用node发布。

免责声明

发行声明 A. 获准公开发行：发行无限制。

本材料基于空军合同编号 FA8721-05-C-0002 和/或 FA8702-15-D-0001 下由负责研究和工程的助理国防部长支持的工作。本材料中表达的任何意见、发现、结论或建议均为作者的观点，不一定反映负责研究和工程的助理国防部长的观点。

Keylime 的许可证从 BSD Clause-2 更改为 Apache 2.0。可以在MIT github 组织上找到原始的 BSD Clause-2 许可代码。