CINXE.COM

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta name="color-scheme" content="light dark"> <title>PEP 480 – Surviving a Compromise of PyPI: End-to-end signing of packages | peps.python.org</title> <link rel="shortcut icon" href="../_static/py.png"> <link rel="canonical" href="https://peps.python.org/pep-0480/"> <link rel="stylesheet" href="../_static/style.css" type="text/css"> <link rel="stylesheet" href="../_static/mq.css" type="text/css"> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" media="(prefers-color-scheme: light)" id="pyg-light"> <link rel="stylesheet" href="../_static/pygments_dark.css" type="text/css" media="(prefers-color-scheme: dark)" id="pyg-dark"> <link rel="alternate" type="application/rss+xml" title="Latest PEPs" href="https://peps.python.org/peps.rss"> <meta property="og:title" content='PEP 480 – Surviving a Compromise of PyPI: End-to-end signing of packages | peps.python.org'> <meta property="og:description" content="Proposed is an extension to PEP 458 that adds support for end-to-end signing and the maximum security model. End-to-end signing allows both PyPI and developers to sign for the distributions that are downloaded by clients. The minimum security model pr..."> <meta property="og:type" content="website"> <meta property="og:url" content="https://peps.python.org/pep-0480/"> <meta property="og:site_name" content="Python Enhancement Proposals (PEPs)"> <meta property="og:image" content="https://peps.python.org/_static/og-image.png"> <meta property="og:image:alt" content="Python PEPs"> <meta property="og:image:width" content="200"> <meta property="og:image:height" content="200"> <meta name="description" content="Proposed is an extension to PEP 458 that adds support for end-to-end signing and the maximum security model. End-to-end signing allows both PyPI and developers to sign for the distributions that are downloaded by clients. The minimum security model pr..."> <meta name="theme-color" content="#3776ab"> </head> <body> <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> <symbol id="svg-sun-half" viewBox="0 0 24 24" pointer-events="all"> <title>Following system colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="9"></circle> <path d="M12 3v18m0-12l4.65-4.65M12 14.3l7.37-7.37M12 19.6l8.85-8.85"></path> </svg> </symbol> <symbol id="svg-moon" viewBox="0 0 24 24" pointer-events="all"> <title>Selected dark colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <path stroke="none" d="M0 0h24v24H0z" fill="none"></path> <path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z"></path> </svg> </symbol> <symbol id="svg-sun" viewBox="0 0 24 24" pointer-events="all"> <title>Selected light colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="5"></circle> <line x1="12" y1="1" x2="12" y2="3"></line> <line x1="12" y1="21" x2="12" y2="23"></line> <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line> <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line> <line x1="1" y1="12" x2="3" y2="12"></line> <line x1="21" y1="12" x2="23" y2="12"></line> <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line> <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line> </svg> </symbol> </svg> <script> document.documentElement.dataset.colour_scheme = localStorage.getItem("colour_scheme") || "auto" </script> <section id="pep-page-section"> <header> <h1>Python Enhancement Proposals</h1> <ul class="breadcrumbs"> <li><a href="https://www.python.org/" title="The Python Programming Language">Python</a> » </li> <li><a href="../pep-0000/">PEP Index</a> » </li> <li>PEP 480</li> </ul> <button id="colour-scheme-cycler" onClick="setColourScheme(nextColourScheme())"> <svg aria-hidden="true" class="colour-scheme-icon-when-auto"><use href="#svg-sun-half"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-dark"><use href="#svg-moon"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-light"><use href="#svg-sun"></use></svg> <span class="visually-hidden">Toggle light / dark / auto colour theme</span> </button> </header> <article> <section id="pep-content"> <h1 class="page-title">PEP 480 – Surviving a Compromise of PyPI: End-to-end signing of packages</h1> <dl class="rfc2822 field-list simple"> <dt class="field-odd">Author<span class="colon">:</span></dt> <dd class="field-odd">Trishank Karthik Kuppusamy <karthik at trishank.com>, Vladimir Diaz <vladimir.diaz at nyu.edu>, Justin Cappos <jcappos at nyu.edu>, Marina Moore <mm9693 at nyu.edu></dd> <dt class="field-even">BDFL-Delegate<span class="colon">:</span></dt> <dd class="field-even">Donald Stufft <donald at stufft.io></dd> <dt class="field-odd">Discussions-To<span class="colon">:</span></dt> <dd class="field-odd"><a class="reference external" href="https://discuss.python.org/t/5666">Discourse thread</a></dd> <dt class="field-even">Status<span class="colon">:</span></dt> <dd class="field-even"><abbr title="Proposal under active discussion and revision">Draft</abbr></dd> <dt class="field-odd">Type<span class="colon">:</span></dt> <dd class="field-odd"><abbr title="Normative PEP with a new feature for Python, implementation change for CPython or interoperability standard for the ecosystem">Standards Track</abbr></dd> <dt class="field-even">Topic<span class="colon">:</span></dt> <dd class="field-even"><a class="reference external" href="../topic/packaging/">Packaging</a></dd> <dt class="field-odd">Requires<span class="colon">:</span></dt> <dd class="field-odd"><a class="reference external" href="../pep-0458/">458</a></dd> <dt class="field-even">Created<span class="colon">:</span></dt> <dd class="field-even">08-Oct-2014</dd> </dl> <hr class="docutils" /> <section id="contents"> <details><summary>Table of Contents</summary><ul class="simple"> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#pep-status">PEP Status</a></li> <li><a class="reference internal" href="#rationale">Rationale</a></li> <li><a class="reference internal" href="#threat-model">Threat Model</a></li> <li><a class="reference internal" href="#definitions">Definitions</a></li> <li><a class="reference internal" href="#maximum-security-model">Maximum Security Model</a></li> <li><a class="reference internal" href="#end-to-end-signing">End-to-End Signing</a></li> <li><a class="reference internal" href="#metadata-signatures-key-management-and-signing-distributions">Metadata Signatures, Key Management, and Signing Distributions</a><ul> <li><a class="reference internal" href="#cryptographic-signature-scheme-ed25519">Cryptographic Signature Scheme: Ed25519</a></li> <li><a class="reference internal" href="#cryptographic-key-files">Cryptographic Key Files</a></li> <li><a class="reference internal" href="#key-management-minilock">Key Management: miniLock</a></li> <li><a class="reference internal" href="#third-party-upload-tools-twine">Third-party Upload Tools: Twine</a></li> <li><a class="reference internal" href="#build-backends">Build backends</a></li> <li><a class="reference internal" href="#automated-signing-solution">Automated Signing Solution</a></li> <li><a class="reference internal" href="#snapshot-process">Snapshot Process</a></li> <li><a class="reference internal" href="#producing-consistent-snapshots">Producing Consistent Snapshots</a></li> <li><a class="reference internal" href="#auditing-snapshots">Auditing Snapshots</a></li> </ul> </li> <li><a class="reference internal" href="#key-compromise-analysis">Key Compromise Analysis</a><ul> <li><a class="reference internal" href="#in-the-event-of-a-key-compromise">In the Event of a Key Compromise</a></li> </ul> </li> <li><a class="reference internal" href="#appendix-a-pypi-build-farm-and-end-to-end-signing">Appendix A: PyPI Build Farm and End-to-End Signing</a></li> <li><a class="reference internal" href="#references">References</a></li> <li><a class="reference internal" href="#acknowledgements">Acknowledgements</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> </details></section> <section id="abstract"> <h2><a class="toc-backref" href="#abstract" role="doc-backlink">Abstract</a></h2> <p>Proposed is an extension to <a class="pep reference internal" href="../pep-0458/" title="PEP 458 – Secure PyPI downloads with signed repository metadata">PEP 458</a> that adds support for end-to-end signing and the maximum security model. End-to-end signing allows both PyPI and developers to sign for the distributions that are downloaded by clients. The minimum security model proposed by <a class="pep reference internal" href="../pep-0458/" title="PEP 458 – Secure PyPI downloads with signed repository metadata">PEP 458</a> supports continuous delivery of distributions (because they are signed by online keys), but that model does not protect distributions in the event that PyPI is compromised. In the minimum security model, attackers who have compromised the signing keys stored on PyPI Infrastructure may sign for malicious distributions. The maximum security model, described in this PEP, retains the benefits of <a class="pep reference internal" href="../pep-0458/" title="PEP 458 – Secure PyPI downloads with signed repository metadata">PEP 458</a> (e.g., immediate availability of distributions that are uploaded to PyPI), but additionally ensures that end-users are not at risk of installing forged software if PyPI is compromised.</p> <p>This PEP requires some changes to the PyPI infrastructure, and some suggested changes for developers who wish to participate in end-to-end signing. These changes include updating the metadata layout from <a class="pep reference internal" href="../pep-0458/" title="PEP 458 – Secure PyPI downloads with signed repository metadata">PEP 458</a> to include delegations to developer keys, adding a process to register developer keys with PyPI, and a change in the upload workflow for developers who take advantage of end-to-end signing. All of these changes are described in detail later in this PEP. Package managers that wish to take advantage of end-to-end signing do not need to do any additional work beyond what is required to consume metadata described in PEP 458.</p> <p>This PEP discusses the changes made to <a class="pep reference internal" href="../pep-0458/" title="PEP 458 – Secure PyPI downloads with signed repository metadata">PEP 458</a> but excludes its informational elements to primarily focus on the maximum security model. For example, an overview of The Update Framework or the basic mechanisms in <a class="pep reference internal" href="../pep-0458/" title="PEP 458 – Secure PyPI downloads with signed repository metadata">PEP 458</a> are not covered here. The changes to <a class="pep reference internal" href="../pep-0458/" title="PEP 458 – Secure PyPI downloads with signed repository metadata">PEP 458</a> include modifications to the snapshot process, key compromise analysis, auditing snapshots, and the steps that should be taken in the event of a PyPI compromise. The signing and key management process that PyPI MAY RECOMMEND is discussed but not strictly defined. How the release process should be implemented to manage keys and metadata is left to the implementors of the signing tools. That is, this PEP delineates the expected cryptographic key type and signature format included in metadata that MUST be uploaded by developers in order to support end-to-end verification of distributions.</p> </section> <section id="pep-status"> <h2><a class="toc-backref" href="#pep-status" role="doc-backlink">PEP Status</a></h2> <p>The community discussed this PEP from 2014 to 2018. Due to the amount of work required to implement this PEP, discussion was deferred until after approval for the precursor step in <a class="pep reference internal" href="../pep-0458/" title="PEP 458 – Secure PyPI downloads with signed repository metadata">PEP 458</a>. As of mid-2020 PEP 458 is approved and implementation is in progress, and the PEP authors aim to gain approval so they can secure appropriate funding for implementation.</p> </section> <section id="rationale"> <h2><a class="toc-backref" href="#rationale" role="doc-backlink">Rationale</a></h2> <p><a class="pep reference internal" href="../pep-0458/" title="PEP 458 – Secure PyPI downloads with signed repository metadata">PEP 458</a> proposes how PyPI should be integrated with The Update Framework (TUF) <a class="footnote-reference brackets" href="#id27" id="id1">[2]</a>. It explains how modern package managers like pip can be made more secure, and the types of attacks that can be prevented if PyPI is modified on the server side to include TUF metadata. Package managers can reference the TUF metadata available on PyPI to download distributions more securely.</p> <p><a class="pep reference internal" href="../pep-0458/" title="PEP 458 – Secure PyPI downloads with signed repository metadata">PEP 458</a> also describes the metadata layout of the PyPI repository and employs the minimum security model, which supports continuous delivery of projects and uses online cryptographic keys to sign the distributions uploaded by developers. Although the minimum security model guards against most attacks on software updaters <a class="footnote-reference brackets" href="#id30" id="id2">[5]</a> <a class="footnote-reference brackets" href="#id31" id="id3">[6]</a>, such as mix-and-match and extraneous dependencies attacks, it can be improved to support end-to-end signing and to prohibit forged distributions in the event that PyPI is compromised.</p> <p><a class="pep reference internal" href="../pep-0480/" title="PEP 480 – Surviving a Compromise of PyPI: End-to-end signing of packages">PEP 480</a> builds on <a class="pep reference internal" href="../pep-0458/" title="PEP 458 – Secure PyPI downloads with signed repository metadata">PEP 458</a> by adding support for developer signing, and reducing the reliance on online keys to prevent malicious distributions. The main strength of <a class="pep reference internal" href="../pep-0458/" title="PEP 458 – Secure PyPI downloads with signed repository metadata">PEP 458</a> and the minimum security model is the automated and simplified release process: developers may upload distributions and then have PyPI sign for their distributions. Much of the release process is handled in an automated fashion by online roles and this approach requires storing cryptographic signing keys on the PyPI infrastructure. Unfortunately, cryptographic keys that are stored online are vulnerable to theft. The maximum security model, proposed in this PEP, permits developers to sign for the distributions that they make available to PyPI users, and does not put end-users at risk of downloading malicious distributions if the online keys stored on PyPI infrastructure are compromised.</p> </section> <section id="threat-model"> <h2><a class="toc-backref" href="#threat-model" role="doc-backlink">Threat Model</a></h2> <p>The threat model assumes the following:</p> <ul class="simple"> <li>Offline keys are safe and securely stored.</li> <li>Attackers can compromise at least one of PyPI’s trusted keys that are stored online, and may do so at once or over a period of time.</li> <li>Attackers can respond to client requests.</li> <li>Attackers may control any number of developer keys for projects a client does not want to install.</li> </ul> <p>Attackers are considered successful if they can cause a client to install (or leave installed) something other than the most up-to-date version of the software the client is updating. When an attacker is preventing the installation of updates, the attacker’s goal is that clients not realize that anything is wrong.</p> </section> <section id="definitions"> <h2><a class="toc-backref" href="#definitions" role="doc-backlink">Definitions</a></h2> <p>The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in <span class="target" id="index-0"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2119.html"><strong>RFC 2119</strong></a>.</p> <p>This PEP focuses on integrating TUF with PyPI; however, the reader is encouraged to read about TUF’s design principles <a class="footnote-reference brackets" href="#id27" id="id4">[2]</a>. It is also RECOMMENDED that the reader be familiar with the TUF specification <a class="footnote-reference brackets" href="#id28" id="id5">[3]</a>, and <a class="pep reference internal" href="../pep-0458/" title="PEP 458 – Secure PyPI downloads with signed repository metadata">PEP 458</a> (which this PEP is extending).</p> <p>The following terms used in this PEP are defined in the Python Packaging Glossary <a class="footnote-reference brackets" href="#id29" id="id6">[4]</a>: <em>project</em>, <em>release</em>, <em>distribution</em>.</p> <p>Terms used in this PEP are defined as follows:</p> <ul class="simple"> <li>Distribution file: A versioned archive file that contains Python packages, modules, and other resource files that are used to distribute a release. The terms <em>distribution file</em>, <em>distribution package</em> <a class="footnote-reference brackets" href="#id29" id="id7">[4]</a>, or simply <em>distribution</em> or <em>package</em> may be used interchangeably in this PEP.</li> <li>Simple index: The HTML page that contains internal links to distribution files.</li> <li>Target files: As a rule of thumb, target files are all files on PyPI whose integrity should be guaranteed with TUF. Typically, this includes distribution files, and PyPI metadata such as simple indices.</li> <li>Roles: Roles in TUF encompass the set of actions a party is authorized to perform, including what metadata they may sign and which packages they are responsible for. There is one <em>root</em> role in PyPI. There are multiple roles whose responsibilities are delegated to them directly or indirectly by the <em>root</em> role. The term “top-level role” refers to the <em>root</em> role and any role delegated by the <em>root</em> role. Each role has a single metadata file that it is trusted to provide.</li> <li>Metadata: Metadata are files that describe roles, other metadata, and target files.</li> <li>Repository: A repository is a resource comprised of named metadata and target files. Clients request metadata and target files stored on a repository.</li> <li>Consistent snapshot: A set of TUF metadata and target files that capture the complete state of all projects on PyPI as they existed at some fixed point in time.</li> <li>Developer: Either the owner or maintainer of a project who is allowed to update TUF metadata, as well as distribution metadata and files for a given project.</li> <li>Online key: A private cryptographic key that MUST be stored on the PyPI server infrastructure. This usually allows automated signing with the key. An attacker who compromises the PyPI infrastructure will be able to immediately read these keys.</li> <li>Offline key: A private cryptographic key that MUST be stored independent of the PyPI server infrastructure. This prevents automated signing with the key. An attacker who compromises the PyPI infrastructure will not be able to immediately read these keys.</li> <li>Threshold signature scheme: A role can increase its resilience to key compromises by specifying that at least t out of n keys are REQUIRED to sign its metadata. A compromise of t-1 keys is insufficient to compromise the role itself. Saying that a role requires (t, n) keys denotes the threshold signature property.</li> </ul> </section> <section id="maximum-security-model"> <h2><a class="toc-backref" href="#maximum-security-model" role="doc-backlink">Maximum Security Model</a></h2> <p>The maximum security model permits developers to sign their projects and to upload signed metadata to PyPI. In the model proposed in this PEP, if the PyPI infrastructure were compromised, attackers would be unable to serve malicious versions of a <em>claimed</em> project without having access to that project’s developer key. Figure 1 depicts the changes made to the metadata layout of the minimum security model, namely that developer roles are now supported and that three new delegated roles exist: <em>claimed</em>, <em>recently-claimed</em>, and <em>unclaimed</em>. The <em>bins</em> role from the minimum security model has been renamed <em>unclaimed</em> and can contain any projects that have not been added to <em>claimed</em>. The <em>unclaimed</em> role functions just as before (i.e., as explained in <a class="pep reference internal" href="../pep-0458/" title="PEP 458 – Secure PyPI downloads with signed repository metadata">PEP 458</a>, projects added to this role are signed by PyPI with an online key). Offline keys provided by developers ensure the strength of the maximum security model over the minimum model. Although the minimum security model supports continuous delivery of projects, all projects are signed by an online key. That is, an attacker is able to corrupt packages in the minimum security model, but not in the maximum model, without also compromising a developer’s key.</p> <img alt="../_images/pep-0480-1.png" class="invert-in-dark-mode" src="../_images/pep-0480-1.png" /> <p>Figure 1: An overview of the metadata layout in the maximum security model. The maximum security model supports continuous delivery and survivable key compromise.</p> <p>Projects that are signed by developers and uploaded to PyPI for the first time are added to the <em>recently-claimed</em> role. The <em>recently-claimed</em> role uses an online key, so projects uploaded for the first time are immediately available to clients. After some time has passed, PyPI administrators MAY periodically move (e.g., every month) projects listed in <em>recently-claimed</em> to the <em>claimed</em> role for maximum security. The <em>claimed</em> role uses an offline key, thus projects added to this role cannot be easily forged if PyPI is compromised.</p> <p>The <em>recently-claimed</em> role is separate from the <em>unclaimed</em> role for usability and efficiency, not security. If new project delegations were prepended to <em>unclaimed</em> metadata, <em>unclaimed</em> would need to be re-downloaded every time a project obtained a key. By separating out new projects, the amount of data retrieved is reduced. From a usability standpoint, it also makes it easier for administrators to see which projects are now claimed. This information is needed when moving keys from <em>recently-claimed</em> to <em>claimed</em>, which is discussed in more detail in the “Producing Consistent Snapshots” section.</p> </section> <section id="end-to-end-signing"> <h2><a class="toc-backref" href="#end-to-end-signing" role="doc-backlink">End-to-End Signing</a></h2> <p>End-to-end signing allows both PyPI and developers to sign for the metadata downloaded by clients. PyPI is trusted to make uploaded projects available to clients (PyPI signs the metadata for this part of the process), and developers sign the distributions that they upload to PyPI.</p> <p>In order to delegate trust to a project, developers are required to submit at least one public key to PyPI. Developers may submit multiple public keys for the same project (for example, one key for each maintainer of the project). PyPI takes all of the project’s public keys and adds them to parent metadata that PyPI then signs. After the initial trust is established, developers are required to sign distributions that they upload to PyPI using at least one public key’s corresponding private key. The signed TUF metadata that developers upload to PyPI includes information like the distribution’s file size and hash, which package managers use to verify distributions that are downloaded.</p> <p>The practical implications of end-to-end signing is the extra administrative work needed to delegate trust to a project, and the signed metadata that developers MUST upload to PyPI along with the distribution. Specifically, PyPI is expected to periodically sign metadata with an offline key by adding projects to the <em>claimed</em> metadata file and signing it. In contrast, projects are only ever signed with an online key in the minimum security model. End-to-end signing does require manual intervention to delegate trust (i.e., to sign metadata with an offline key), but this is a one-time cost and projects have stronger protections against PyPI compromises thereafter.</p> </section> <section id="metadata-signatures-key-management-and-signing-distributions"> <h2><a class="toc-backref" href="#metadata-signatures-key-management-and-signing-distributions" role="doc-backlink">Metadata Signatures, Key Management, and Signing Distributions</a></h2> <p>This section discusses the tools, signature scheme, and signing methods that PyPI MAY recommend to implementors of the signing tools. Developers are expected to use these tools to sign and upload distributions to PyPI. To summarize the RECOMMENDED tools and schemes discussed in the subsections below, developers MAY generate cryptographic keys and sign metadata (with the Ed25519 signature scheme) in some automated fashion, where the metadata includes the information required to verify the authenticity of the distribution. Developers then upload metadata to PyPI, where it will be available for download by package managers such as pip (i.e., package managers that support TUF metadata). The entire process is transparent to the end-users (using a package manager that supports TUF) that download distributions from PyPI.</p> <p>The first three subsections (Cryptographic Signature Scheme, Cryptographic Key Files, and Key Management) cover the cryptographic components of the developer release process. That is, which key type PyPI supports, how keys may be stored, and how keys may be generated. The two subsections that follow the first three discuss the PyPI modules that SHOULD be modified to support TUF metadata. For example, Twine and Distutils are two projects that SHOULD be modified. Finally, the last subsection goes over the automated key management and signing solution that is RECOMMENDED for the signing tools.</p> <p>TUF’s design is flexible with respect to cryptographic key types, signatures, and signing methods. The tools, modification, and methods discussed in the following sections are RECOMMENDATIONS for the implementors of the signing tools.</p> <section id="cryptographic-signature-scheme-ed25519"> <h3><a class="toc-backref" href="#cryptographic-signature-scheme-ed25519" role="doc-backlink">Cryptographic Signature Scheme: Ed25519</a></h3> <p>The package manager (pip) shipped with CPython MUST work on non-CPython interpreters and cannot have dependencies that have to be compiled (i.e., the PyPI+TUF integration MUST NOT require compilation of C extensions in order to verify cryptographic signatures). Verification of signatures MUST be done in Python, and verifying RSA <a class="footnote-reference brackets" href="#id33" id="id8">[8]</a> signatures in pure-Python may be impractical due to speed. Therefore, PyPI MAY use the <a class="reference external" href="http://ed25519.cr.yp.to/">Ed25519</a> signature scheme.</p> <p>Ed25519 <a class="footnote-reference brackets" href="#id34" id="id10">[9]</a> is a public-key signature system that uses small cryptographic signatures and keys. A <a class="reference external" href="https://github.com/pyca/ed25519">pure-Python implementation</a> of the Ed25519 signature scheme is available. Verification of Ed25519 signatures is fast even when performed in Python.</p> </section> <section id="cryptographic-key-files"> <h3><a class="toc-backref" href="#cryptographic-key-files" role="doc-backlink">Cryptographic Key Files</a></h3> <p>The implementation MAY encrypt key files with AES-256-CTR-Mode and strengthen passwords with PBKDF2-HMAC-SHA256 (100K iterations by default, but this may be overridden by the developer). The current Python implementation of TUF can use any cryptographic library (support for PyCA cryptography will be added in the future), may override the default number of PBKDF2 iterations, and the KDF tweaked to taste.</p> </section> <section id="key-management-minilock"> <h3><a class="toc-backref" href="#key-management-minilock" role="doc-backlink">Key Management: miniLock</a></h3> <p>An easy-to-use key management solution is needed. One solution is to derive a private key from a password so that developers do not have to manage cryptographic key files across multiple computers. <a class="reference external" href="https://github.com/kaepora/miniLock#-minilock">miniLock</a> is an example of how this can be done. Developers may view the cryptographic key as a secondary password. miniLock also works well with a signature scheme like Ed25519, which only needs a very small key.</p> </section> <section id="third-party-upload-tools-twine"> <h3><a class="toc-backref" href="#third-party-upload-tools-twine" role="doc-backlink">Third-party Upload Tools: Twine</a></h3> <p>Third-party tools like <a class="reference external" href="https://github.com/pypa/twine">Twine</a> MAY be modified (if they wish to support distributions that include TUF metadata) to sign and upload developer projects to PyPI. Twine is a utility for interacting with PyPI that uses TLS to upload distributions, and prevents MITM attacks on usernames and passwords.</p> </section> <section id="build-backends"> <h3><a class="toc-backref" href="#build-backends" role="doc-backlink">Build backends</a></h3> <p>Build backends MAY be modified to sign metadata and to upload signed distributions to PyPI.</p> </section> <section id="automated-signing-solution"> <h3><a class="toc-backref" href="#automated-signing-solution" role="doc-backlink">Automated Signing Solution</a></h3> <p>An easy-to-use key management solution is RECOMMENDED for developers. One approach is to generate a cryptographic private key from a user password, akin to miniLock. Although developer signatures can remain optional, this approach may be inadequate due to the great number of potentially unsigned dependencies each distribution may have. If any one of these dependencies is unsigned, it negates any benefit the project gains from signing its own distribution (i.e., attackers would only need to compromise one of the unsigned dependencies to attack end-users). Requiring developers to manually sign distributions and manage keys is expected to render key signing an unused feature.</p> <p>A default, PyPI-mediated key management and package signing solution that is <a class="reference external" href="https://en.wikipedia.org/wiki/Transparency_%28human%E2%80%93computer_interaction%29">transparent</a> to developers and does not require a key escrow (sharing of encrypted private keys with PyPI) is RECOMMENDED for the signing tools. Additionally, the signing tools SHOULD circumvent the sharing of private keys across multiple machines of each developer. This means that the key management solution SHOULD support multiple keys for each project.</p> <p>The following outlines an automated signing solution that a new developer MAY follow to upload a distribution to PyPI:</p> <ol class="arabic simple"> <li>Register a PyPI project.</li> <li>Enter a secondary password (independent of the PyPI user account password).</li> <li>Optional: Add a new identity to the developer’s PyPI user account from a second machine (after a password prompt).</li> <li>Upload project.</li> <li>Optional: Other maintainers associated with the project may log in and enter a secondary password to add their identity to the project.</li> </ol> <p>Step 1 is the normal procedure followed by developers to <a class="reference external" href="https://pypi.python.org/pypi?:action=register_form">register a PyPI project</a>.</p> <p>Step 2 generates an encrypted key file (private), uploads an Ed25519 public key to PyPI, and signs the TUF metadata that is generated for the distribution.</p> <p>Optionally adding a new identity from a second machine, by simply entering a password, in step 3 also generates an encrypted private key file and uploads an Ed25519 public key to PyPI. Separate identities MAY be created to allow a developer, to sign releases on multiple machines. An existing verified identity (its public key is contained in project metadata or has been uploaded to PyPI) signs for new identities. By default, project metadata has a signature threshold of “1” and other verified identities may create new releases to satisfy the threshold.</p> <p>Step 4 uploads the distribution file and TUF metadata to PyPI. The “Snapshot Process” section discusses in detail the procedure followed by developers to upload a distribution to PyPI.</p> <p>Step 5 allows other maintainers to generate an encrypted key file, in a similar manner to step 2. These keys SHOULD be uploaded to PyPI and added to the TUF metadata. This key MAY be used to upload future releases of the project.</p> <p>Generation of cryptographic files and signatures is transparent to the developers in the default case: developers need not be aware that packages are automatically signed. However, the signing tools should be flexible; developers may want to generate their own keys and handle the key management themselves. In this case, the developers may simply upload their public key(s) to PyPI.</p> <p>The <a class="reference external" href="https://github.com/theupdateframework/tuf/blob/develop/tuf/README.md">repository</a> and <a class="reference external" href="https://github.com/theupdateframework/tuf/blob/develop/tuf/README-developer-tools.md">developer</a> TUF tools currently support all of the recommendations previously mentioned, except for the automated signing solution, which SHOULD be added to Distlib, Twine, and other third-party signing tools. The automated signing solution calls available repository tool functions to sign metadata and to generate the cryptographic key files.</p> </section> <section id="snapshot-process"> <h3><a class="toc-backref" href="#snapshot-process" role="doc-backlink">Snapshot Process</a></h3> <p>The snapshot process is fairly simple and SHOULD be automated. The snapshot process MUST keep in memory the latest working set of <em>root</em>, <em>targets</em>, and delegated roles. Every minute or so the snapshot process will sign for this latest working set. (Recall that project uploads continuously inform the snapshot process about the latest delegated metadata in a concurrency-safe manner. The snapshot process will actually sign for a copy of the latest working set while the latest working set in memory will be updated with information that is continuously communicated by the project transaction processes.) The snapshot process MUST generate and sign new <em>timestamp</em> metadata that will vouch for the metadata (<em>root</em>, <em>targets</em>, and delegated roles) generated in the previous step. Finally, the snapshot process MUST make available to clients the new <em>timestamp</em> and <em>snapshot</em> metadata representing the latest snapshot.</p> <p>A <em>claimed</em> or <em>recently-claimed</em> project will need to upload in its transaction to PyPI not just targets (a simple index as well as distributions) but also TUF metadata. The project MAY do so by uploading a ZIP file containing two directories, /metadata/ (containing delegated targets metadata files) and /targets/ (containing targets such as the project simple index and distributions that are signed by the delegated targets metadata).</p> <p>Whenever the project uploads metadata or target files to PyPI, PyPI SHOULD check the project TUF metadata for at least the following properties:</p> <ul class="simple"> <li>A threshold number of the developers keys registered with PyPI by that project MUST have signed for the delegated targets metadata file that represents the “root” of targets for that project (e.g. metadata/targets/ project.txt).</li> <li>The signatures of delegated targets metadata files MUST be valid.</li> <li>The delegated targets metadata files MUST NOT have expired.</li> <li>The delegated targets metadata MUST be consistent with the targets.</li> <li>A delegator MUST NOT delegate targets that were not delegated to itself by another delegator.</li> <li>A delegatee MUST NOT sign for targets that were not delegated to itself by a delegator.</li> </ul> <p>If PyPI chooses to check the project TUF metadata, then PyPI MAY choose to reject publishing any set of metadata or target files that do not meet these requirements.</p> <p>PyPI MUST enforce access control by ensuring that each project can only write to the TUF metadata for which it is responsible. It MUST do so by ensuring that project upload processes write to the correct metadata as well as correct locations within those metadata. For example, a project upload process for an unclaimed project MUST write to the correct target paths in the correct delegated unclaimed metadata for the targets of the project.</p> <p>On rare occasions, PyPI MAY wish to extend the TUF metadata format for projects in a backward-incompatible manner. Note that PyPI will NOT be able to automatically rewrite existing TUF metadata on behalf of projects in order to upgrade the metadata to the new backward-incompatible format because this would invalidate the signatures of the metadata as signed by developer keys. Instead, package managers SHOULD be written to recognize and handle multiple incompatible versions of TUF metadata so that claimed and recently-claimed projects could be offered a reasonable time to migrate their metadata to newer but backward-incompatible formats. One mechanism for handling this version change is described in TAP <a class="reference external" href="https://github.com/theupdateframework/taps/blob/master/tap14.md">14</a>.</p> <p>If PyPI eventually runs out of disk space to produce a new consistent snapshot, then PyPI MAY then use something like a “mark-and-sweep” algorithm to delete sufficiently outdated consistent snapshots. That is, only outdated metadata like <em>timestamp</em> and <em>snapshot</em> that are no longer used are deleted. Specifically, in order to preserve the latest consistent snapshot, PyPI would walk objects – beginning from the root (<em>timestamp</em>) – of the latest consistent snapshot, mark all visited objects, and delete all unmarked objects. The last few consistent snapshots may be preserved in a similar fashion. Deleting a consistent snapshot will cause clients to see nothing except HTTP 404 responses to any request for a target of the deleted consistent snapshot. Clients SHOULD then retry (as before) their requests with the latest consistent snapshot.</p> <p>All package managers that support TUF metadata MUST be modified to download every metadata and target file (except for <em>timestamp</em> metadata) by including, in the request for the file, the cryptographic hash of the file in the filename. Following the filename convention RECOMMENDED in the next subsection, a request for the file at filename.ext will be transformed to the equivalent request for the file at digest.filename.</p> <p>Finally, PyPI SHOULD use a <a class="reference external" href="https://en.wikipedia.org/wiki/Transaction_log">transaction log</a> to record project transaction processes and queues so that it will be easier to recover from errors after a server failure.</p> </section> <section id="producing-consistent-snapshots"> <h3><a class="toc-backref" href="#producing-consistent-snapshots" role="doc-backlink">Producing Consistent Snapshots</a></h3> <p>PyPI is responsible for updating, depending on the project, either the <em>claimed</em>, <em>recently-claimed</em>, or <em>unclaimed</em> metadata and associated delegated metadata. Every project MUST upload its set of metadata and targets in a single transaction. The uploaded set of files is called the “project transaction.” How PyPI MAY validate files in a project transaction is discussed in a later section. The focus of this section is on how PyPI will respond to a project transaction.</p> <p>Every metadata and target file MUST include in its filename the <a class="reference external" href="http://docs.python.org/2/library/hashlib.html#hashlib.hash.hexdigest">hex digest</a> of its <a class="reference external" href="https://en.wikipedia.org/wiki/BLAKE_(hash_function)#BLAKE2">BLAKE2b-256</a> hash, which PyPI may prepend to filenames after the files have been uploaded. For this PEP, it is RECOMMENDED that PyPI adopt a simple convention of the form: <em>digest.filename</em>, where filename is the original filename without a copy of the hash, and digest is the hex digest of the hash.</p> <p>When an unclaimed project uploads a new transaction, a project transaction process MUST add all new target files and relevant delegated unclaimed metadata. The project upload process MUST inform the snapshot process about new delegated unclaimed metadata.</p> <p>When a <em>recently-claimed</em> project uploads a new transaction, a project upload process MUST add all new target files and delegated targets metadata for the project. If the project is new, then the project upload process MUST also add new <em>recently-claimed</em> metadata with the public keys (which MUST be part of the transaction) for the project. <em>recently-claimed</em> projects have a threshold value of “1” set by the upload process. Finally, the project upload process MUST inform the snapshot process about new <em>recently-claimed</em> metadata, as well as the current set of delegated targets metadata for the project.</p> <p>The upload process for a claimed project is slightly different in that PyPI administrators periodically move (a manual process that MAY occur every two weeks to a month) projects from the <em>recently-claimed</em> role to the <em>claimed</em> role. (Moving a project from <em>recently-claimed</em> to <em>claimed</em> is a manual process because PyPI administrators have to use an offline key to sign the claimed project’s distribution.) A project upload process MUST then add new <em>recently-claimed</em> and <em>claimed</em> metadata to reflect this migration. As is the case for a <em>recently-claimed</em> project, the project upload process MUST always add all new target files and delegated targets metadata for the claimed project. Finally, the project upload process MUST inform the consistent snapshot process about new <em>recently-claimed</em> or <em>claimed</em> metadata, as well as the current set of delegated targets metadata for the project.</p> <p>Project upload processes SHOULD be automated, except when PyPI administrators move a project from the <em>recently-claimed</em> role to the <em>claimed</em> role. Project upload processes MUST also be applied atomically: either all metadata and target files – or none of them – are added. The project transaction processes and snapshot process SHOULD work concurrently. Finally, project upload processes SHOULD keep in memory the latest <em>claimed</em>, <em>recently-claimed</em>, and <em>unclaimed</em> metadata so that they will be correctly updated in new consistent snapshots.</p> <p>The queue MAY be processed concurrently in order of appearance, provided that the following rules are observed:</p> <ol class="arabic simple"> <li>No pair of project upload processes may concurrently work on the same project.</li> <li>No pair of project upload processes may concurrently work on <em>unclaimed</em> projects that belong to the same delegated <em>unclaimed</em> role.</li> <li>No pair of project upload processes may concurrently work on new recently-claimed projects.</li> <li>No pair of project upload processes may concurrently work on new claimed projects.</li> <li>No project upload process may work on a new claimed project while another project upload process is working on a new recently-claimed project and vice versa.</li> </ol> <p>These rules MUST be observed to ensure that metadata is not read from or written to inconsistently.</p> </section> <section id="auditing-snapshots"> <h3><a class="toc-backref" href="#auditing-snapshots" role="doc-backlink">Auditing Snapshots</a></h3> <p>If a malicious party compromises PyPI, they can sign arbitrary files with any of the online keys. The roles with offline keys (i.e., <em>root</em> and <em>targets</em>) are still protected. To safely recover from a repository compromise, snapshots should be audited to ensure that files are only restored to trusted versions.</p> <p>When a repository compromise has been detected, the integrity of three types of information must be validated:</p> <ol class="arabic simple"> <li>If the online keys of the repository have been compromised, they can be revoked by having the <em>targets</em> role sign new metadata, delegated to a new key.</li> <li>If the role metadata on the repository has been changed, this will impact the metadata that is signed by online keys. Any role information created since the compromise should be discarded. As a result, developers of new projects will need to re-register their projects.</li> <li>If the packages themselves may have been tampered with, they can be validated using the stored hash information for packages that existed in trusted metadata before the compromise. Also, new distributions that are signed by developers in the <em>claimed</em> role may be safely retained. However, any distributions signed by developers in the <em>recently-claimed</em> or <em>unclaimed</em> roles should be discarded.</li> </ol> <p>In order to safely restore snapshots in the event of a compromise, PyPI SHOULD maintain a small number of its own mirrors to copy PyPI snapshots according to some schedule. The mirroring protocol can be used immediately for this purpose. The mirrors must be secured and isolated such that they are responsible only for mirroring PyPI. The mirrors can be checked against one another to detect accidental or malicious failures.</p> <p>Another approach is to periodically generate the cryptographic hash of each <em>snapshot</em> and tweet it. For example, upon receiving the tweet, a user comes forward with the actual metadata and the repository maintainers are then able to verify the metadata’s cryptographic hash. Alternatively, PyPI may periodically archive its own versions of <em>snapshots</em> rather than rely on externally provided metadata. In this case, PyPI SHOULD take the cryptographic hash of every package on the repository and store this data on an offline device. If any package hash has changed, this indicates an attack has occurred.</p> <p>Attacks that serve different versions of metadata or that freeze a version of a package at a specific version can be handled by TUF with techniques such as implicit key revocation and metadata mismatch detection <a class="footnote-reference brackets" href="#id27" id="id22">[2]</a>.</p> </section> </section> <section id="key-compromise-analysis"> <h2><a class="toc-backref" href="#key-compromise-analysis" role="doc-backlink">Key Compromise Analysis</a></h2> <p>This PEP has covered the maximum security model, the TUF roles that should be added to support continuous delivery of distributions, how to generate and sign the metadata of each role, and how to support distributions that have been signed by developers. The remaining sections discuss how PyPI SHOULD audit repository metadata, and the methods PyPI can use to detect and recover from a PyPI compromise.</p> <p>Table 1 summarizes a few of the attacks possible when a threshold number of private cryptographic keys (belonging to any of the PyPI roles) are compromised. The leftmost column lists the roles (or a combination of roles) that have been compromised, and the columns to the right show whether the compromised roles leaves clients susceptible to malicious updates, freeze attacks, or metadata inconsistency attacks.</p> <table class="docutils align-default"> <thead> <tr class="row-odd"><th class="head">Role Compromise</th> <th class="head">Malicious Updates</th> <th class="head">Freeze Attack</th> <th class="head">Metadata Inconsistency Attacks</th> </tr> </thead> <tbody> <tr class="row-even"><td>timestamp</td> <td>NO snapshot and targets or any of the delegated roles need to cooperate</td> <td>YES limited by earliest root, targets, or bin metadata expiry time</td> <td>NO snapshot needs to cooperate</td> </tr> <tr class="row-odd"><td>snapshot</td> <td>NO timestamp and targets or any of the delegated roles need to cooperate</td> <td>NO timestamp needs to cooperate</td> <td>NO timestamp needs to cooperate</td> </tr> <tr class="row-even"><td>timestamp <em>AND</em> snapshot</td> <td>NO targets or any of the delegated roles need to cooperate</td> <td>YES limited by earliest root, targets, or bin metadata expiry time</td> <td>YES limited by earliest root, targets, or bin metadata expiry time</td> </tr> <tr class="row-odd"><td>targets <em>OR</em> <strong>claimed</strong> <em>OR</em> recently-claimed <em>OR</em> unclaimed <em>OR</em> <strong>project</strong></td> <td>NO timestamp and snapshot need to cooperate</td> <td>NOT APPLICABLE need timestamp and snapshot</td> <td>NOT APPLICABLE need timestamp and snapshot</td> </tr> <tr class="row-even"><td>(timestamp <em>AND</em> snapshot) <em>AND</em> <strong>project</strong></td> <td>YES</td> <td>YES limited by earliest root, targets, or bin metadata expiry time</td> <td>YES limited by earliest root, targets, or bin metadata expiry time</td> </tr> <tr class="row-odd"><td>(timestamp <em>AND</em> snapshot) <em>AND</em> (recently-claimed <em>OR</em> unclaimed)</td> <td>YES but only of projects not delegated by claimed</td> <td>YES limited by earliest root, targets, claimed, recently-claimed, project, or unclaimed metadata expiry time</td> <td>YES limited by earliest root, targets, claimed, recently-claimed, project, or unclaimed metadata expiry time</td> </tr> <tr class="row-even"><td>(timestamp <em>AND</em> snapshot) <em>AND</em> (targets <em>OR</em> <strong>claimed</strong>)</td> <td>YES</td> <td>YES limited by earliest root, targets, claimed, recently-claimed, project, or unclaimed metadata expiry time</td> <td>YES limited by earliest root, targets, claimed, recently-claimed, project, or unclaimed metadata expiry time</td> </tr> <tr class="row-odd"><td>root</td> <td>YES</td> <td>YES</td> <td>YES</td> </tr> </tbody> </table> <p>Table 1: Attacks that are possible by compromising certain combinations of role keys. In <a class="reference external" href="https://mail.python.org/pipermail/distutils-sig/2013-September/022755.html">September 2013</a>, it was shown how the latest version (at the time) of pip was susceptible to these attacks and how TUF could protect users against them <a class="footnote-reference brackets" href="#id32" id="id23">[7]</a>. Roles signed by offline keys are in <strong>bold</strong>.</p> <p>Note that compromising <em>targets</em> or any delegated role (except for project targets metadata) does not immediately allow an attacker to serve malicious updates. The attacker must also compromise the <em>timestamp</em> and <em>snapshot</em> roles (which are both online and therefore more likely to be compromised). This means that in order to launch any attack, one must not only be able to act as a man-in-the-middle, but also compromise the <em>timestamp</em> key (or compromise the <em>root</em> keys and sign a new <em>timestamp</em> key). To launch any attack other than a freeze attack, one must also compromise the <em>snapshot</em> key. Finally, a compromise of the PyPI infrastructure MAY introduce malicious updates to <em>recently-claimed</em> projects because the keys for these roles are online.</p> <section id="in-the-event-of-a-key-compromise"> <h3><a class="toc-backref" href="#in-the-event-of-a-key-compromise" role="doc-backlink">In the Event of a Key Compromise</a></h3> <p>A key compromise means that a threshold of keys belonging to developers or the roles on PyPI, as well as the PyPI infrastructure, have been compromised and used to sign new metadata on PyPI.</p> <p>If a threshold number of developer keys of a project have been compromised, the project MUST take the following steps:</p> <ol class="arabic simple"> <li>The project metadata and targets MUST be restored to the last known good consistent snapshot where the project was not known to be compromised. This can be done by developers repackaging and resigning all targets with the new keys.</li> <li>The project’s metadata MUST have its version numbers incremented, expiry times suitably extended, and signatures renewed.</li> </ol> <p>Whereas PyPI MUST take the following steps:</p> <ol class="arabic simple"> <li>Revoke the compromised developer keys from the <em>recently-claimed</em> or <em>claimed</em> role. This is done by replacing the compromised developer keys with newly issued developer keys.</li> <li>A new timestamped consistent snapshot MUST be issued.</li> </ol> <p>If a threshold number of <em>timestamp</em>, <em>snapshot</em>, <em>recently-claimed</em>, or <em>unclaimed</em> keys have been compromised, then PyPI MUST take the following steps:</p> <ol class="arabic simple"> <li>Revoke the <em>timestamp</em>, <em>snapshot</em>, and <em>targets</em> role keys from the root role. This is done by replacing the compromised <em>timestamp</em>, <em>snapshot</em>, and <em>targets</em> keys with newly issued keys.</li> <li>Revoke the <em>recently-claimed</em> and <em>unclaimed</em> keys from the <em>targets</em> role by replacing their keys with newly issued keys. Sign the new targets role metadata and discard the new keys (because, as we explained earlier, this increases the security of targets metadata).</li> <li>Clear all targets or delegations in the <em>recently-claimed</em> role and delete all associated delegated targets metadata. Recently registered projects SHOULD register their developer keys again with PyPI.</li> <li>All targets of the <em>recently-claimed</em> and <em>unclaimed</em> roles SHOULD be compared with the last known good consistent snapshot where none of the timestamp, snapshot, recently-claimed, or unclaimed keys were known to have been compromised. Added, updated, or deleted targets in the compromised consistent snapshot that do not match the last known good consistent snapshot SHOULD be restored to their previous versions. After ensuring the integrity of all unclaimed targets, the unclaimed metadata MUST be regenerated.</li> <li>The <em>recently-claimed</em> and <em>unclaimed</em> metadata MUST have their version numbers incremented, expiry times suitably extended, and signatures renewed.</li> <li>A new timestamped consistent snapshot MUST be issued.</li> </ol> <p>This would preemptively protect all of these roles even though only one of them may have been compromised.</p> <p>If a threshold number of the <em>targets</em> or <em>claimed</em> keys have been compromised, then there is little that an attacker would be able do without the <em>timestamp</em> and <em>snapshot</em> keys. In this case, PyPI MUST simply revoke the compromised <em>targets</em> or <em>claimed</em> keys by replacing them with new keys in the <em>root</em> and <em>targets</em> roles, respectively.</p> <p>If a threshold number of the <em>timestamp</em>, <em>snapshot</em>, and <em>claimed</em> keys have been compromised, then PyPI MUST take the following steps in addition to the steps taken when either the <em>timestamp</em> or <em>snapshot</em> keys are compromised:</p> <ol class="arabic simple"> <li>Revoke the <em>claimed</em> role keys from the targets role and replace them with newly issued keys.</li> <li>All project targets of the claimed roles SHOULD be compared with the last known good consistent snapshot where none of the <em>timestamp</em>, <em>snapshot</em>, or <em>claimed</em> keys were known to have been compromised. Added, updated, or deleted targets in the compromised consistent snapshot that do not match the last known good consistent snapshot MAY be restored to their previous versions. After ensuring the integrity of all claimed project targets, the <em>claimed</em> metadata MUST be regenerated.</li> <li>The claimed metadata MUST have their version numbers incremented, expiry times suitably extended, and signatures renewed.</li> </ol> <p>Following these steps would preemptively protect all of these roles even though only one of them may have been compromised.</p> <p>If a threshold number of <em>root</em> keys have been compromised, then PyPI MUST take the steps taken when the <em>targets</em> role has been compromised. All of the <em>root</em> keys must also be replaced.</p> <p>It is also RECOMMENDED that PyPI sufficiently document compromises with security bulletins. These security bulletins will be most informative when users of pip-with-TUF are unable to install or update a project because the keys for the <em>timestamp</em>, <em>snapshot</em>, or <em>root</em> roles are no longer valid. Users could then visit the PyPI web site to consult security bulletins that would help to explain why users are no longer able to install or update, and then take action accordingly. When a threshold number of <em>root</em> keys have not been revoked due to a compromise, then new <em>root</em> metadata may be safely updated because a threshold number of existing <em>root</em> keys will be used to sign for the integrity of the new <em>root</em> metadata. TUF clients will be able to verify the integrity of the new <em>root</em> metadata with a threshold number of previously known <em>root</em> keys. This will be the common case. In the worst case, where a threshold number of <em>root</em> keys have been revoked due to a compromise, an end-user may choose to update new <em>root</em> metadata with <a class="reference external" href="https://en.wikipedia.org/wiki/Out-of-band#Authentication">out-of-band</a> mechanisms.</p> </section> </section> <section id="appendix-a-pypi-build-farm-and-end-to-end-signing"> <h2><a class="toc-backref" href="#appendix-a-pypi-build-farm-and-end-to-end-signing" role="doc-backlink">Appendix A: PyPI Build Farm and End-to-End Signing</a></h2> <p>PyPI administrators intend to support a central build farm. The PyPI build farm will auto-generate a <a class="reference external" href="http://wheel.readthedocs.org/en/latest/">Wheel</a>, for each distribution that is uploaded by developers, on PyPI infrastructure and on supported platforms. Package managers will likely install projects by downloading these PyPI Wheels (which can be installed much faster than source distributions) rather than the source distributions signed by developers. The implications of having a central build farm with end-to-end signing SHOULD be investigated before the maximum security model is implemented.</p> <p>An issue with a central build farm and end-to-end signing is that developers are unlikely to sign Wheel distributions once they have been generated on PyPI infrastructure. However, generating wheels from source distributions that are signed by developers can still be beneficial, provided that building Wheels is a deterministic process. If deterministic builds are infeasible, developers may delegate trust of these wheels to a PyPI role that signs for wheels with an online key.</p> </section> <section id="references"> <h2><a class="toc-backref" href="#references" role="doc-backlink">References</a></h2> <aside class="footnote-list brackets"> <aside class="footnote brackets" id="id27" role="doc-footnote"> <dt class="label" id="id27">[2]<em> (<a href='#id1'>1</a>, <a href='#id4'>2</a>, <a href='#id22'>3</a>) </em></dt> <dd><a class="reference external" href="https://theupdateframework.io/papers/survivable-key-compromise-ccs2010.pdf">https://theupdateframework.io/papers/survivable-key-compromise-ccs2010.pdf</a></aside> <aside class="footnote brackets" id="id28" role="doc-footnote"> <dt class="label" id="id28">[<a href="#id5">3</a>]</dt> <dd><a class="reference external" href="https://theupdateframework.github.io/specification/latest/index.html">https://theupdateframework.github.io/specification/latest/index.html</a></aside> <aside class="footnote brackets" id="id29" role="doc-footnote"> <dt class="label" id="id29">[4]<em> (<a href='#id6'>1</a>, <a href='#id7'>2</a>) </em></dt> <dd><a class="reference external" href="https://packaging.python.org/en/latest/glossary/">https://packaging.python.org/en/latest/glossary/</a></aside> <aside class="footnote brackets" id="id30" role="doc-footnote"> <dt class="label" id="id30">[<a href="#id2">5</a>]</dt> <dd><a class="reference external" href="https://github.com/theupdateframework/pip/wiki/Attacks-on-software-repositories">https://github.com/theupdateframework/pip/wiki/Attacks-on-software-repositories</a></aside> <aside class="footnote brackets" id="id31" role="doc-footnote"> <dt class="label" id="id31">[<a href="#id3">6</a>]</dt> <dd><a class="reference external" href="https://theupdateframework.io/papers/attacks-on-package-managers-ccs2008.pdf">https://theupdateframework.io/papers/attacks-on-package-managers-ccs2008.pdf</a></aside> <aside class="footnote brackets" id="id32" role="doc-footnote"> <dt class="label" id="id32">[<a href="#id23">7</a>]</dt> <dd><a class="reference external" href="https://mail.python.org/pipermail/distutils-sig/2013-September/022755.html">https://mail.python.org/pipermail/distutils-sig/2013-September/022755.html</a></aside> <aside class="footnote brackets" id="id33" role="doc-footnote"> <dt class="label" id="id33">[<a href="#id8">8</a>]</dt> <dd><a class="reference external" href="https://en.wikipedia.org/wiki/RSA_(cryptosystem">https://en.wikipedia.org/wiki/RSA_(cryptosystem</a>)</aside> <aside class="footnote brackets" id="id34" role="doc-footnote"> <dt class="label" id="id34">[<a href="#id10">9</a>]</dt> <dd><a class="reference external" href="https://ed25519.cr.yp.to/">https://ed25519.cr.yp.to/</a></aside> </aside> </section> <section id="acknowledgements"> <h2><a class="toc-backref" href="#acknowledgements" role="doc-backlink">Acknowledgements</a></h2> <p>This material is based upon work supported by the National Science Foundation under Grants No. CNS-1345049 and CNS-0959138. Any opinions, findings, and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the National Science Foundation.</p> <p>We thank Alyssa Coghlan, Daniel Holth, Donald Stufft, Sumana Harihareswara, and the distutils-sig community in general for helping us to think about how to usably and efficiently integrate TUF with PyPI.</p> <p>Roger Dingledine, Sebastian Hahn, Nick Mathewson, Martin Peck and Justin Samuel helped us to design TUF from its predecessor Thandy of the Tor project.</p> <p>We appreciate the efforts of Konstantin Andrianov, Geremy Condra, Zane Fisher, Justin Samuel, Tian Tian, Santiago Torres, John Ward, and Yuyu Zheng to develop TUF.</p> </section> <section id="copyright"> <h2><a class="toc-backref" href="#copyright" role="doc-backlink">Copyright</a></h2> <p>This document has been placed in the public domain.</p> </section> </section> <hr class="docutils" /> <p>Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-0480.rst">https://github.com/python/peps/blob/main/peps/pep-0480.rst</a></p> <p>Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0480.rst">2023-10-11 12:05:51 GMT</a></p> </article> <nav id="pep-sidebar"> <h2>Contents</h2> <ul> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#pep-status">PEP Status</a></li> <li><a class="reference internal" href="#rationale">Rationale</a></li> <li><a class="reference internal" href="#threat-model">Threat Model</a></li> <li><a class="reference internal" href="#definitions">Definitions</a></li> <li><a class="reference internal" href="#maximum-security-model">Maximum Security Model</a></li> <li><a class="reference internal" href="#end-to-end-signing">End-to-End Signing</a></li> <li><a class="reference internal" href="#metadata-signatures-key-management-and-signing-distributions">Metadata Signatures, Key Management, and Signing Distributions</a><ul> <li><a class="reference internal" href="#cryptographic-signature-scheme-ed25519">Cryptographic Signature Scheme: Ed25519</a></li> <li><a class="reference internal" href="#cryptographic-key-files">Cryptographic Key Files</a></li> <li><a class="reference internal" href="#key-management-minilock">Key Management: miniLock</a></li> <li><a class="reference internal" href="#third-party-upload-tools-twine">Third-party Upload Tools: Twine</a></li> <li><a class="reference internal" href="#build-backends">Build backends</a></li> <li><a class="reference internal" href="#automated-signing-solution">Automated Signing Solution</a></li> <li><a class="reference internal" href="#snapshot-process">Snapshot Process</a></li> <li><a class="reference internal" href="#producing-consistent-snapshots">Producing Consistent Snapshots</a></li> <li><a class="reference internal" href="#auditing-snapshots">Auditing Snapshots</a></li> </ul> </li> <li><a class="reference internal" href="#key-compromise-analysis">Key Compromise Analysis</a><ul> <li><a class="reference internal" href="#in-the-event-of-a-key-compromise">In the Event of a Key Compromise</a></li> </ul> </li> <li><a class="reference internal" href="#appendix-a-pypi-build-farm-and-end-to-end-signing">Appendix A: PyPI Build Farm and End-to-End Signing</a></li> <li><a class="reference internal" href="#references">References</a></li> <li><a class="reference internal" href="#acknowledgements">Acknowledgements</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> <br> <a id="source" href="https://github.com/python/peps/blob/main/peps/pep-0480.rst">Page Source (GitHub)</a> </nav> </section> <script src="../_static/colour_scheme.js"></script> <script src="../_static/wrap_tables.js"></script> <script src="../_static/sticky_banner.js"></script> </body> </html>