加密签名方案：Ed25519

与 CPython 一起提供的软件包管理器 (pip) 必须在非 CPython 解释器上工作，并且不能有必须编译的依赖项（即，PyPI+TUF 集成必须不需要编译 C 扩展才能验证加密签名）。签名的验证必须在 Python 中完成，并且由于速度原因，在纯 Python 中验证 RSA [8] 签名可能不切实际。因此，PyPI 可以使用 Ed25519 签名方案。

Ed25519 [9] 是一种使用小型加密签名和密钥的公钥签名系统。 Ed25519 签名方案的纯 Python 实现 可供使用。即使在 Python 中执行，Ed25519 签名的验证速度也很快。

加密密钥文件

实现可以使用 AES-256-CTR 模式加密密钥文件，并使用 PBKDF2-HMAC-SHA256 加强密码（默认情况下为 100K 次迭代，但这可以由开发者覆盖）。TUF 的当前 Python 实现可以使用任何加密库（将来会添加对 PyCA 加密的支持），可以覆盖默认的 PBKDF2 迭代次数，并且可以根据需要调整 KDF。

密钥管理：miniLock

需要一个易于使用的密钥管理解决方案。一种解决方案是从密码派生私钥，以便开发者不必在多台计算机上管理加密密钥文件。miniLock 是如何做到这一点的一个示例。开发者可以将加密密钥视为辅助密码。miniLock 也适用于像 Ed25519 这样的签名方案，它只需要一个非常小的密钥。

第三方上传工具：Twine

诸如 Twine 之类的第三方工具可以修改（如果他们希望支持包含 TUF 元数据的发行版）以签署并将开发者项目上传到 PyPI。Twine 是一个用于与 PyPI 交互的实用程序，它使用 TLS 上传发行版，并防止对用户名和密码进行中间人攻击。

构建后端

构建后端可以修改以签署元数据并将已签署的发行版上传到 PyPI。

自动签名解决方案

建议开发者使用易于使用的密钥管理解决方案。一种方法是从用户密码生成加密私钥，类似于 miniLock。尽管开发者签名可以保持可选，但由于每个发行版可能具有的大量潜在未签名依赖项，这种方法可能不足。如果这些依赖项中的任何一个未签名，则会抵消项目通过签署自己的发行版获得的任何好处（即，攻击者只需要破坏其中一个未签名的依赖项即可攻击最终用户）。要求开发者手动签署发行版和管理密钥预计会使密钥签名成为一个未使用的功能。

建议为签名工具提供一个默认的、由 PyPI 介导的密钥管理和软件包签名解决方案，该解决方案对开发者是 透明的，并且不需要密钥托管（与 PyPI 共享加密私钥）。此外，签名工具应该避免在每个开发者的多台机器之间共享私钥。这意味着密钥管理解决方案应该支持每个项目的多个密钥。

以下是新开发者可以按照上传发行版到 PyPI 的自动化签名解决方案的概述

1. 注册 PyPI 项目。
2. 输入辅助密码（独立于 PyPI 用户帐户密码）。
3. 可选：从第二台机器（在密码提示后）向开发者的 PyPI 用户帐户添加新身份。
4. 上传项目。
5. 可选：与项目相关的其他维护者可以登录并输入辅助密码以将其身份添加到项目中。

步骤 1 是开发者遵循的正常程序，以 注册 PyPI 项目。

步骤 2 生成加密密钥文件（私有），将 Ed25519 公钥上传到 PyPI，并签署为发行版生成的 TUF 元数据。

在步骤 3 中，可选地从第二台机器添加新身份，只需输入密码，这也会生成一个加密的私钥文件并将 Ed25519 公钥上传到 PyPI。可以创建单独的身份以允许开发者在多台机器上签署发布。现有的已验证身份（其公钥包含在项目元数据中或已上传到 PyPI）为新身份签名。默认情况下，项目元数据的签名阈值为“1”，其他已验证的身份可以创建新发布以满足阈值。

步骤 4 将发行版文件和 TUF 元数据上传到 PyPI。“快照过程”部分详细讨论了开发者遵循的上传发行版到 PyPI 的过程。

步骤 5 允许其他维护者以类似于步骤 2 的方式生成加密密钥文件。这些密钥应该上传到 PyPI 并添加到 TUF 元数据中。此密钥可以用来上传项目的未来版本。

在默认情况下，加密文件和签名的生成对开发者是透明的：开发者不需要知道软件包是自动签名的。但是，签名工具应该灵活；开发者可能希望生成自己的密钥并自行处理密钥管理。在这种情况下，开发者可以简单地将他们的公钥上传到 PyPI。

存储库 和 开发者 TUF 工具目前支持前面提到的所有建议，除了自动化签名解决方案，该解决方案应该添加到 Distlib、Twine 和其他第三方签名工具中。可用的存储库工具功能调用自动化签名解决方案来签署元数据并生成加密密钥文件。

快照流程

快照过程相当简单，**应该**自动化。快照过程**必须**将最新的工作集（包含root、targets和委派角色）保存在内存中。大约每分钟，快照过程都会对这个最新的工作集进行签名。（回想一下，项目上传会持续以并发安全的方式告知快照过程最新的委派元数据。快照过程实际上会对最新工作集的副本进行签名，而内存中的最新工作集将使用项目事务过程持续通信的信息进行更新。）快照过程**必须**生成并签名新的timestamp元数据，以证明上一步生成的元数据（root、targets和委派角色）的有效性。最后，快照过程**必须**向客户端提供新的timestamp和snapshot元数据，表示最新的快照。

一个claimed或recently-claimed项目需要在其上传到PyPI的事务中，不仅包含目标文件（简单的索引以及发行版），还需要包含TUF元数据。项目**可以**通过上传一个包含两个目录的ZIP文件来实现，/metadata/（包含委派目标元数据文件）和/targets/（包含目标文件，例如项目简单索引和由委派目标元数据签名的发行版）。

每当项目将元数据或目标文件上传到PyPI时，PyPI**应该**至少检查项目TUF元数据的以下属性

• 由该项目在PyPI上注册的开发人员密钥中的**阈值**数量**必须**已对表示该项目目标“根”的委派目标元数据文件进行签名（例如metadata/targets/ project.txt）。
• 委派目标元数据文件的签名**必须**有效。
• 委派目标元数据文件**不得**过期。
• 委派目标元数据**必须**与目标文件一致。
• 委托方**不得**委托未被其他委托方委托给自己的目标文件。
• 受托方**不得**为未被委托方委托给自己的目标文件签名。

如果PyPI选择检查项目TUF元数据，那么PyPI**可以**选择拒绝发布任何不满足这些要求的元数据或目标文件集。

PyPI**必须**通过确保每个项目只能写入其负责的TUF元数据来执行访问控制。它**必须**通过确保项目上传过程写入正确的元数据以及这些元数据中的正确位置来实现。例如，未声明项目的项目上传过程**必须**写入相应委派未声明元数据中项目目标的正确目标路径。

在极少数情况下，PyPI**可能**希望以向后不兼容的方式扩展项目的TUF元数据格式。请注意，PyPI**无法**代表项目自动重写现有的TUF元数据以将其升级到新的向后不兼容格式，因为这会使开发人员密钥签名的元数据签名失效。相反，包管理器**应该**被编写为识别和处理多个不兼容版本的TUF元数据，以便声明和最近声明的项目可以获得合理的时间将其元数据迁移到更新但向后不兼容的格式。TAP 14中描述了一种处理此版本更改的机制。

如果PyPI最终耗尽磁盘空间以生成新的一致快照，那么PyPI**可以**使用类似“标记-清除”的算法删除足够旧的一致快照。也就是说，只删除不再使用的过时的元数据，例如timestamp和snapshot。具体来说，为了保留最新的快照，PyPI将遍历对象——从最新一致快照的根（timestamp）开始——标记所有访问过的对象，并删除所有未标记的对象。最后几个一致快照可以以类似的方式保留。删除一致快照将导致客户端除了对已删除一致快照的目标的任何请求返回HTTP 404响应之外，什么也看不到。客户端**应该**然后（像以前一样）使用最新的快照重试他们的请求。

所有支持TUF元数据的包管理器**必须**修改为下载每个元数据和目标文件（除了timestamp元数据），并在文件请求中包含文件名中的文件加密哈希。按照下一小节中**建议**的文件名约定，对filename.ext文件的请求将转换为对digest.filename文件的等效请求。

最后，PyPI**应该**使用事务日志记录项目事务过程和队列，以便在服务器故障后更容易从错误中恢复。

生成一致的快照

PyPI负责根据项目更新claimed、recently-claimed或unclaimed元数据以及相关的委派元数据。每个项目**必须**在单个事务中上传其元数据和目标文件集。上传的文件集称为“项目事务”。PyPI如何**可能**验证项目事务中的文件将在后面的章节中讨论。本节重点介绍PyPI将如何响应项目事务。

每个元数据和目标文件**必须**在其文件名中包含其十六进制摘要的BLAKE2b-256哈希值，PyPI可以在文件上传后将其添加到文件名之前。对于本PEP，**建议**PyPI采用以下简单的约定：digest.filename，其中filename是原始文件名，不包含哈希值的副本，digest是哈希值的十六进制摘要。

当未声明的项目上传新的事务时，项目事务过程**必须**添加所有新的目标文件和相关的委派未声明元数据。项目上传过程**必须**通知快照过程新的委派未声明元数据。

当recently-claimed项目上传新的事务时，项目上传过程**必须**添加所有新的目标文件和项目的委派目标元数据。如果项目是新的，那么项目上传过程**必须**还添加新的recently-claimed元数据，以及项目的公钥（**必须**是事务的一部分）。recently-claimed项目的阈值由上传过程设置为“1”。最后，项目上传过程**必须**通知快照过程新的recently-claimed元数据以及项目当前的委派目标元数据集。

声明项目的上传过程略有不同，因为PyPI管理员会定期（**可能**每两周到一个月）将项目从recently-claimed角色迁移到claimed角色。（将项目从recently-claimed迁移到claimed是一个手动过程，因为PyPI管理员必须使用脱机密钥来签署声明项目的发布。）然后，项目上传过程**必须**添加新的recently-claimed和claimed元数据以反映此迁移。与recently-claimed项目一样，项目上传过程**必须**始终添加所有新的目标文件和声明项目的委派目标元数据。最后，项目上传过程**必须**通知一致快照过程新的recently-claimed或claimed元数据以及项目当前的委派目标元数据集。

项目上传过程**应该**自动化，除非PyPI管理员将项目从recently-claimed角色迁移到claimed角色。项目上传过程**必须**也原子地应用：要么所有元数据和目标文件都被添加，要么都不添加。项目事务过程和快照过程**应该**并发工作。最后，项目上传过程**应该**将最新的claimed、recently-claimed和unclaimed元数据保存在内存中，以便它们在新的快照中被正确更新。

队列**可以**根据出现顺序并发处理，前提是遵守以下规则

1. 任何一对项目上传过程**不得**同时处理同一个项目。
2. 任何一对项目上传过程**不得**同时处理属于同一委派unclaimed角色的unclaimed项目。
3. 任何一对项目上传过程**不得**同时处理新的recently-claimed项目。
4. 任何一对项目上传过程**不得**同时处理新的claimed项目。
5. 当另一个项目上传过程正在处理新的recently-claimed项目时，任何项目上传过程**不得**处理新的claimed项目，反之亦然。

**必须**遵守这些规则以确保元数据不会被不一致地读取或写入。

审计快照

如果恶意方破坏了PyPI，他们可以使用任何在线密钥对任意文件进行签名。具有脱机密钥的角色（即，root和targets）仍然受到保护。为了安全地从存储库破坏中恢复，应审核快照以确保文件仅恢复到受信任的版本。

当检测到存储库遭到破坏时，必须验证三种类型的信息的完整性

1. 如果存储库的在线密钥遭到破坏，可以通过让targets角色签署委派给新密钥的新元数据来撤销它们。
2. 如果存储库上的角色元数据已被更改，这将影响由在线密钥签名的元数据。自破坏以来创建的任何角色信息都应丢弃。因此，新项目的开发者需要重新注册他们的项目。
3. 如果包本身可能已被篡改，可以使用存储在受信任元数据中存在的包的哈希信息进行验证。此外，由claimed角色中的开发人员签名的新的发行版可以安全地保留。但是，应丢弃由recently-claimed或unclaimed角色中的开发人员签名的任何发行版。

为了在发生破坏的情况下安全地恢复快照，PyPI**应该**维护少量自己的镜像，以根据某些计划复制PyPI快照。镜像协议可以立即用于此目的。镜像必须是安全的和隔离的，以便它们只负责镜像PyPI。可以相互检查镜像以检测意外或恶意的故障。

另一种方法是定期生成每个snapshot的加密哈希并发布到Twitter。例如，在收到推文后，用户会提供实际的元数据，然后存储库维护者能够验证元数据的加密哈希。或者，PyPI可以定期存档其自己的snapshot版本，而不是依赖外部提供的元数据。在这种情况下，PyPI**应该**获取存储库中每个包的加密哈希，并将此数据存储在脱机设备上。如果任何包哈希已更改，则表示已发生攻击。

提供不同版本元数据或将包的版本冻结在特定版本的攻击可以通过TUF使用隐式密钥撤销和元数据不匹配检测等技术来处理[2]。

密钥泄露事件

密钥泄露意味着开发人员或 PyPI 上的角色以及 PyPI 基础设施的密钥已达到阈值数量被泄露，并用于在 PyPI 上签名新的元数据。

如果项目的开发人员密钥达到阈值数量被泄露，则该项目**必须**采取以下步骤

1. 项目元数据和目标**必须**恢复到最后已知的良好一致快照，在该快照中项目尚未知被泄露。开发人员可以使用新密钥重新打包和重新签名所有目标来做到这一点。
2. 项目的元数据**必须**将其版本号递增、适当延长过期时间并更新签名。

而 PyPI **必须**采取以下步骤

1. 从最近已声明或已声明的角色中撤销被泄露的开发人员密钥。这可以通过用新发行的开发人员密钥替换被泄露的开发人员密钥来完成。
2. **必须**发布新的带时间戳的一致快照。

如果时间戳、快照、最近已声明或未声明密钥达到阈值数量被泄露，则 PyPI **必须**采取以下步骤

1. 从根角色中撤销时间戳、快照和目标角色密钥。这可以通过用新发行的密钥替换被泄露的时间戳、快照和目标密钥来完成。
2. 通过用新发行的密钥替换其密钥，从目标角色中撤销最近已声明和未声明密钥。对新的目标角色元数据进行签名并丢弃新密钥（因为，正如我们之前解释的那样，这提高了目标元数据的安全性）。
3. 清除最近已声明角色中的所有目标或委托，并删除所有相关的委托目标元数据。最近注册的项目**应该**再次向 PyPI 注册其开发人员密钥。
4. 所有最近已声明和未声明角色的目标**应该**与最后已知的良好一致快照进行比较，在该快照中，尚未知时间戳、快照、最近已声明或未声明密钥中的任何一个被泄露。在被泄露的一致快照中添加、更新或删除的目标，如果与最后已知的良好一致快照不匹配，**应该**恢复到其先前版本。在确保所有未声明目标的完整性后，**必须**重新生成未声明的元数据。
5. 最近已声明和未声明元数据**必须**将其版本号递增、适当延长过期时间并更新签名。
6. **必须**发布新的带时间戳的一致快照。

这将预先保护所有这些角色，即使可能只有一个角色被泄露。

如果目标或已声明密钥达到阈值数量被泄露，那么在没有时间戳和快照密钥的情况下，攻击者几乎无法做任何事情。在这种情况下，PyPI **必须**简单地撤销被泄露的目标或已声明密钥，方法是在根和目标角色中分别用新密钥替换它们。

如果时间戳、快照和已声明密钥达到阈值数量被泄露，则 PyPI **必须**采取以下步骤，此外还必须采取在时间戳或快照密钥被泄露时采取的步骤

1. 从目标角色中撤销已声明角色密钥，并用新发行的密钥替换它们。
2. 所有已声明角色的项目目标**应该**与最后已知的良好一致快照进行比较，在该快照中，尚未知时间戳、快照或已声明密钥中的任何一个被泄露。在被泄露的一致快照中添加、更新或删除的目标，如果与最后已知的良好一致快照不匹配，**可能**恢复到其先前版本。在确保所有已声明项目目标的完整性后，**必须**重新生成已声明元数据。
3. 已声明的元数据**必须**将其版本号递增、适当延长过期时间并更新签名。

遵循这些步骤将预先保护所有这些角色，即使可能只有一个角色被泄露。

如果根密钥达到阈值数量被泄露，则 PyPI **必须**采取在目标角色被泄露时采取的步骤。所有根密钥也必须被替换。

还**建议** PyPI 使用安全公告充分记录泄露事件。当使用 TUF 的 pip 用户无法安装或更新项目（因为时间戳、快照或根角色的密钥不再有效）时，这些安全公告将提供最有用的信息。然后，用户可以访问 PyPI 网站查阅安全公告，以帮助解释为什么用户无法再安装或更新，然后采取相应的措施。当由于泄露而没有撤销阈值数量的根密钥时，可以安全地更新新的根元数据，因为阈值数量的现有根密钥将用于对新根元数据的完整性进行签名。TUF 客户端将能够使用阈值数量的先前已知的根密钥验证新根元数据的完整性。这将是常见情况。在最坏的情况下，如果由于泄露而撤销了阈值数量的根密钥，则最终用户可以选择使用带外机制更新新的根元数据。