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 740 – Index support for digital attestations | peps.python.org</title> <link rel="shortcut icon" href="../_static/py.png"> <link rel="canonical" href="https://peps.python.org/pep-0740/"> <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 740 – Index support for digital attestations | peps.python.org'> <meta property="og:description" content="This PEP proposes a collection of changes related to the upload and distribution of digitally signed attestations and metadata used to verify them on a Python package repository, such as PyPI."> <meta property="og:type" content="website"> <meta property="og:url" content="https://peps.python.org/pep-0740/"> <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="This PEP proposes a collection of changes related to the upload and distribution of digitally signed attestations and metadata used to verify them on a Python package repository, such as PyPI."> <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 740</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> Toggle light / dark / auto colour theme </button> </header> <article> <section id="pep-content"> <h1 class="page-title">PEP 740 – Index support for digital attestations</h1> <dl class="rfc2822 field-list simple"> <dt class="field-odd">Author:</dt> <dd class="field-odd">William Woodruff <william at yossarian.net>, Facundo Tuesca <facundo.tuesca at trailofbits.com>, Dustin Ingram <di at python.org></dd> <dt class="field-even">Sponsor:</dt> <dd class="field-even">Donald Stufft <donald at stufft.io></dd> <dt class="field-odd">PEP-Delegate:</dt> <dd class="field-odd">Donald Stufft <donald at stufft.io></dd> <dt class="field-even">Discussions-To:</dt> <dd class="field-even"><a class="reference external" href="https://discuss.python.org/t/pep-740-index-support-for-digital-attestations/44498">Discourse thread</a></dd> <dt class="field-odd">Status:</dt> <dd class="field-odd"><abbr title="Provisionally accepted but additional feedback needed">Provisional</abbr></dd> <dt class="field-even">Type:</dt> <dd class="field-even"><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-odd">Topic:</dt> <dd class="field-odd"><a class="reference external" href="../topic/packaging/">Packaging</a></dd> <dt class="field-even">Created:</dt> <dd class="field-even">08-Jan-2024</dd> <dt class="field-odd">Post-History:</dt> <dd class="field-odd"><a class="reference external" href="https://discuss.python.org/t/pre-pep-exposing-trusted-publisher-provenance-on-pypi/42337" title="Discourse thread">02-Jan-2024</a>, <a class="reference external" href="https://discuss.python.org/t/pep-740-index-support-for-digital-attestations/44498" title="Discourse thread">29-Jan-2024</a></dd> <dt class="field-even">Resolution:</dt> <dd class="field-even"><a class="reference external" href="https://discuss.python.org/t/pep-740-index-support-for-digital-attestations/44498/26">Discourse message</a></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="#rationale-and-motivation">Rationale and Motivation</a><ul> <li><a class="reference internal" href="#design-considerations">Design Considerations</a></li> <li><a class="reference internal" href="#previous-work">Previous Work</a><ul> <li><a class="reference internal" href="#pgp-signatures">PGP signatures</a></li> <li><a class="reference internal" href="#wheel-signatures">Wheel signatures</a></li> </ul> </li> </ul> </li> <li><a class="reference internal" href="#specification">Specification</a><ul> <li><a class="reference internal" href="#upload-endpoint-changes">Upload endpoint changes</a></li> <li><a class="reference internal" href="#index-changes">Index changes</a><ul> <li><a class="reference internal" href="#simple-index">Simple Index</a></li> <li><a class="reference internal" href="#json-based-simple-api">JSON-based Simple API</a></li> </ul> </li> <li><a class="reference internal" href="#attestation-objects">Attestation objects</a><ul> <li><a class="reference internal" href="#attestation-statement-and-signature-generation">Attestation statement and signature generation</a></li> </ul> </li> <li><a class="reference internal" href="#provenance-objects">Provenance objects</a><ul> <li><a class="reference internal" href="#changes-to-provenance-objects">Changes to provenance objects</a></li> </ul> </li> <li><a class="reference internal" href="#attestation-verification">Attestation verification</a></li> </ul> </li> <li><a class="reference internal" href="#security-implications">Security Implications</a><ul> <li><a class="reference internal" href="#cryptographic-agility-in-attestations">Cryptographic agility in attestations</a></li> <li><a class="reference internal" href="#index-trust">Index trust</a></li> </ul> </li> <li><a class="reference internal" href="#recommendations">Recommendations</a></li> <li><a class="reference internal" href="#appendix-1-example-trusted-publisher-representation">Appendix 1: Example Trusted Publisher Representation</a></li> <li><a class="reference internal" href="#appendix-2-data-models-for-transparency-log-entries">Appendix 2: Data models for Transparency Log Entries</a></li> <li><a class="reference internal" href="#appendix-3-simple-json-api-size-considerations">Appendix 3: Simple JSON API size considerations</a></li> <li><a class="reference internal" href="#appendix-4-example-attestation-statement">Appendix 4: Example attestation statement</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> This PEP proposes a collection of changes related to the upload and distribution of digitally signed attestations and metadata used to verify them on a Python package repository, such as PyPI. These changes have two subcomponents: <ul class="simple"> <li>Changes to the currently unstandardized PyPI upload API, allowing clients to upload digital attestations as <a class="reference internal" href="#attestation-object">attestation objects</a>;</li> <li>Changes to the <a class="reference external" href="https://packaging.python.org/en/latest/specifications/simple-repository-api/#simple-repository-api" title="(in Python Packaging User Guide)">HTML and JSON “simple” APIs</a>, allowing clients to retrieve both digital attestations and <a class="reference external" href="https://docs.pypi.org/trusted-publishers/">Trusted Publishing</a> metadata for individual release files as <a class="reference internal" href="#provenance-object">provenance objects</a>.</li> </ul> This PEP does not make a policy recommendation around mandatory digital attestations on release uploads or their subsequent verification by installing clients like <code class="docutils literal notranslate">pip</code>. </section> <section id="rationale-and-motivation"> <h2><a class="toc-backref" href="#rationale-and-motivation" role="doc-backlink">Rationale and Motivation</a></h2> Desire for digital signatures on Python packages has been repeatedly expressed by both package maintainers and downstream users: <ul class="simple"> <li>Maintainers wish to demonstrate the integrity and authenticity of their package uploads;</li> <li>Individual downstream users wish to verify package integrity and authenticity without placing additional trust in their index’s honesty;</li> <li>“Bulk” downstream users (such as Operating System distributions) wish to perform similar verifications and potentially re-expose or countersign for their own downstream packaging ecosystems.</li> </ul> This proposal seeks to accommodate each of the above use cases. Additionally, this proposal identifies the following motivations: <ul> <li>Verifiable provenance for Python package distributions: many Python packages currently contain unauthenticated provenance metadata, such as URLs for source hosts. A cryptographic attestation format could enable strong authenticated links between these packages and their source hosts, allowing both the index and downstream users to cryptographically verify that a package originates from its claimed source repository.</li> <li>Raising attacker requirements: an attacker who seeks to take over a Python package can be described along sophistication (unsophisticated to sophisticated) and targeting dimensions (opportunistic to targeted).Digital attestations impose additional sophistication requirements: the attacker must be sufficiently sophisticated to access private signing material (or signing identities). </li> <li>Index verifiability: in the status quo, the only attestation provided by the index is an optional PGP signature per release file (see <a class="reference internal" href="#pgp-signatures">PGP signatures</a>). These signatures are not (and cannot be) checked by the index either for well-formedness or for validity, since the index has no mechanism for identifying the right public key for the signature. This PEP overcomes this limitation by ensuring that <a class="reference internal" href="#provenance-object">provenance objects</a> contain all of the metadata needed by the index to verify an attestation’s validity.</li> </ul> This PEP proposes a generic attestation format, containing an <a class="reference internal" href="#payload-and-signature-generation">attestation statement for signature generation</a>, with the expectation that index providers adopt the format with a suitable source of identity for signature verification, such as Trusted Publishing. <section id="design-considerations"> <h3><a class="toc-backref" href="#design-considerations" role="doc-backlink">Design Considerations</a></h3> This PEP identifies the following design considerations when evaluating both its own proposed changes and previous work in the same or adjacent areas of Python packaging: <ol class="arabic"> <li>Index accessibility: digital attestations for Python packages are ideally retrievable directly from the index itself, as “detached” resources.This both simplifies some compatibility concerns (by avoiding the need to modify the distribution formats themselves) and also simplifies the behavior of potential installing clients (by allowing them to retrieve each attestation before its corresponding package without needing to do streaming decompression). </li> <li>Verification by the index itself: in addition to enabling verification by installing clients, each digital attestation is ideally verifiable in some form by the index itself.This both increases the overall quality of attestations uploaded to the index (preventing, for example, users from accidentally uploading incorrect or invalid attestations) and also enables UI and UX refinements on the index itself (such as a “provenance” view for each uploaded package). </li> <li>General applicability: digital attestations should be applicable to any and every package uploaded to the index, regardless of its format (sdist or wheel) or interior contents.</li> <li>Metadata support: this PEP refers to “digital attestations” rather than just “digital signatures” to emphasize the ideal presence of additional metadata within the cryptographic envelope.For example, to prevent domain separation between a distribution’s name and its contents, this PEP uses ‘<a class="reference external" href="https://github.com/in-toto/attestation/blob/v1.0/spec/v1.0/statement.md">Statements</a>’ from the <a class="reference external" href="https://in-toto.io/">in-toto project</a> to bind the distribution’s contents (via SHA-256 digest) to its filename. </li> </ol> </section> <section id="previous-work"> <h3><a class="toc-backref" href="#previous-work" role="doc-backlink">Previous Work</a></h3> <section id="pgp-signatures"> <h4><a class="toc-backref" href="#pgp-signatures" role="doc-backlink">PGP signatures</a></h4> PyPI and other indices have historically supported PGP signatures on uploaded distributions. These could be supplied during upload, and could be retrieved by installing clients via the <code class="docutils literal notranslate">data-gpg-sig</code> attribute in the <a class="pep reference internal" href="../pep-0503/" title="PEP 503 – Simple Repository API">PEP 503</a> API, the <code class="docutils literal notranslate">gpg-sig</code> key on the <a class="pep reference internal" href="../pep-0691/" title="PEP 691 – JSON-based Simple API for Python Package Indexes">PEP 691</a> API, or via an adjacent <code class="docutils literal notranslate">.asc</code>-suffixed URL. PGP signature uploads have been disabled on PyPI since <a class="reference external" href="https://blog.pypi.org/posts/2023-05-23-removing-pgp/">May 2023</a>, after <a class="reference external" href="https://blog.yossarian.net/2023/05/21/PGP-signatures-on-PyPI-worse-than-useless">an investigation</a> determined that the majority of signatures (which, themselves, constituted a tiny percentage of overall uploads) could not be associated with a public key or otherwise meaningfully verified. In their previously supported form on PyPI, PGP signatures satisfied considerations (1) and (3) above but not (2) (owing to the need for external keyservers and key distribution) or (4) (due to PGP signatures typically being constructed over just an input file, without any associated signed metadata). </section> <section id="wheel-signatures"> <h4><a class="toc-backref" href="#wheel-signatures" role="doc-backlink">Wheel signatures</a></h4> <a class="pep reference internal" href="../pep-0427/" title="PEP 427 – The Wheel Binary Package Format 1.0">PEP 427</a> (and its <a class="reference external" href="https://packaging.python.org/en/latest/specifications/binary-distribution-format/#binary-distribution-format" title="(in Python Packaging User Guide)">living PyPA counterpart</a>) specify the <a class="reference external" href="https://packaging.python.org/en/latest/glossary/#term-Wheel" title="(in Python Packaging User Guide)">wheel format</a>. This format includes accommodations for digital signatures embedded directly into the wheel, in either JWS or S/MIME format. These signatures are specified over a <a class="pep reference internal" href="../pep-0376/" title="PEP 376 – Database of Installed Python Distributions">PEP 376</a> RECORD, which is modified to include a cryptographic digest for each recorded file in the wheel. While wheel signatures are fully specified, they do not appear to be broadly used; the official <a class="reference external" href="https://github.com/pypa/wheel">wheel tooling</a> deprecated signature generation and verification support <a class="reference external" href="https://wheel.readthedocs.io/en/stable/news.html">in 0.32.0</a>, which was released in 2018. Additionally, wheel signatures do not satisfy any of the above considerations (due to the “attached” nature of the signatures, non-verifiability on the index itself, and support for wheels only). </section> </section> </section> <section id="specification"> <h2><a class="toc-backref" href="#specification" role="doc-backlink">Specification</a></h2> <section id="upload-endpoint-changes"> <h3><a class="toc-backref" href="#upload-endpoint-changes" role="doc-backlink">Upload endpoint changes</a></h3> The current upload API is not standardized. However, we propose the following changes to it: <ul class="simple"> <li>In addition to the current top-level <code class="docutils literal notranslate">content</code> and <code class="docutils literal notranslate">gpg_signature</code> fields, the index SHALL accept <code class="docutils literal notranslate">attestations</code> as an additional multipart form field.</li> <li>The new <code class="docutils literal notranslate">attestations</code> field SHALL be a JSON array.</li> <li>The <code class="docutils literal notranslate">attestations</code> array SHALL have one or more items, each a JSON object representing an individual attestation.</li> <li>Each attestation object MUST be verifiable by the index. If the index fails to verify any attestation in <code class="docutils literal notranslate">attestations</code>, it MUST reject the upload. The format of attestation objects is defined under <a class="reference internal" href="#attestation-object">Attestation objects</a> and the process for verifying attestations is defined under <a class="reference internal" href="#attestation-verification">Attestation verification</a>.</li> </ul> </section> <section id="index-changes"> <h3><a class="toc-backref" href="#index-changes" role="doc-backlink">Index changes</a></h3> <section id="simple-index"> <h4><a class="toc-backref" href="#simple-index" role="doc-backlink">Simple Index</a></h4> The following changes are made to the <a class="reference external" href="https://packaging.python.org/en/latest/specifications/simple-repository-api/#simple-repository-api-base" title="(in Python Packaging User Guide)">simple repository API</a>: <ul> <li>When an uploaded file has one or more attestations, the index MAY provide a provenance file containing attestations associated with a given distribution. The format of the provenance file SHALL be a JSON-encoded <a class="reference internal" href="#provenance-object">provenance object</a>, which SHALL contain the file’s attestations.The location of the provenance file is signaled by the index via the <code class="docutils literal notranslate">data-provenance</code> attribute. </li> <li>When a provenance file is present, the index MAY include a <code class="docutils literal notranslate">data-provenance</code> attribute on its file link. The value of the <code class="docutils literal notranslate">data-provenance</code> attribute SHALL be a fully qualified URL, signaling the the file’s provenance can be found at that URL. This URL MUST represent a <a class="reference external" href="https://www.chromium.org/Home/chromium-security/prefer-secure-origins-for-powerful-new-features/">secure origin</a>.The following table provides examples of release file URLs, <code class="docutils literal notranslate">data-provenance</code> values, and their resulting provenance file URLs. <table class="docutils align-default"> <thead> <tr class="row-odd"><th class="head">File URL</th> <th class="head"><code class="docutils literal notranslate">data-provenance</code></th> <th class="head">Provenance URL</th> </tr> </thead> <tbody> <tr class="row-even"><td><a class="reference external" href="https://example.com/sampleproject-1.2.3.tar.gz">https://example.com/sampleproject-1.2.3.tar.gz</a></td> <td><code class="docutils literal notranslate">https://example.com/sampleproject-1.2.3.tar.gz.provenance</code></td> <td><a class="reference external" href="https://example.com/sampleproject-1.2.3.tar.gz.provenance">https://example.com/sampleproject-1.2.3.tar.gz.provenance</a></td> </tr> <tr class="row-odd"><td><a class="reference external" href="https://example.com/sampleproject-1.2.3.tar.gz">https://example.com/sampleproject-1.2.3.tar.gz</a></td> <td><code class="docutils literal notranslate">https://other.example.com/sampleproject-1.2.3.tar.gz/provenance</code></td> <td><a class="reference external" href="https://other.example.com/sampleproject-1.2.3.tar.gz/provenance">https://other.example.com/sampleproject-1.2.3.tar.gz/provenance</a></td> </tr> <tr class="row-even"><td><a class="reference external" href="https://example.com/sampleproject-1.2.3.tar.gz">https://example.com/sampleproject-1.2.3.tar.gz</a></td> <td><code class="docutils literal notranslate">../relative</code></td> <td>(invalid: not a fully qualified URL)</td> </tr> <tr class="row-odd"><td><a class="reference external" href="https://example.com/sampleproject-1.2.3.tar.gz">https://example.com/sampleproject-1.2.3.tar.gz</a></td> <td><code class="docutils literal notranslate">http://unencrypted.example.com/provenance</code></td> <td>(invalid: not a secure origin)</td> </tr> </tbody> </table> </li> <li>The index MAY choose to modify the provenance file. For example, the index MAY permit adding additional attestations and verification materials, such as attestations from third-party auditors or other services.See <a class="reference internal" href="#changes-to-provenance-objects">Changes to provenance objects</a> for an additional discussion of reasons why a file’s provenance may change. </li> </ul> </section> <section id="json-based-simple-api"> <h4><a class="toc-backref" href="#json-based-simple-api" role="doc-backlink">JSON-based Simple API</a></h4> The following changes are made to the <a class="reference external" href="https://packaging.python.org/en/latest/specifications/simple-repository-api/#simple-repository-api-json" title="(in Python Packaging User Guide)">JSON simple API</a>: <ul> <li>When an uploaded file has one or more attestations, the index MAY include a <code class="docutils literal notranslate">provenance</code> key in the <code class="docutils literal notranslate">file</code> dictionary for that file.The value of the <code class="docutils literal notranslate">provenance</code> key SHALL be either a JSON string or <code class="docutils literal notranslate">null</code>. If <code class="docutils literal notranslate">provenance</code> is not <code class="docutils literal notranslate">null</code>, it SHALL be a URL to the associated provenance file. See <a class="reference internal" href="#appendix-3">Appendix 3: Simple JSON API size considerations</a> for an explanation of the technical decision to embed the SHA-256 digest in the JSON API, rather than the full <a class="reference internal" href="#provenance-object">provenance object</a>. </li> </ul> These changes require a version change to the JSON API: <ul class="simple"> <li>The <code class="docutils literal notranslate">api-version</code> SHALL specify version 1.3 or later.</li> </ul> </section> </section> <section id="attestation-objects"> <h3><a class="toc-backref" href="#attestation-objects" role="doc-backlink">Attestation objects</a></h3> An attestation object is a JSON object with several required keys; applications or signers may include additional keys so long as all explicitly listed keys are provided. The required layout of an attestation object is provided as pseudocode below. <div class="highlight-python notranslate"><div class="highlight"><pre>@dataclass class Attestation: version: Literal[1] """ The attestation object's version, which is always 1. """ verification_material: VerificationMaterial """ Cryptographic materials used to verify `envelope`. """ envelope: Envelope """ The enveloped attestation statement and signature. """ @dataclass class Envelope: statement: bytes """ The attestation statement. This is represented as opaque bytes on the wire (encoded as base64), but it MUST be an JSON in-toto v1 Statement. """ signature: bytes """ A signature for the above statement, encoded as base64. """ @dataclass class VerificationMaterial: certificate: str """ The signing certificate, as `base64(DER(cert))`. """ transparency_entries: list[object] """ One or more transparency log entries for this attestation's signature and certificate. """ </pre></div> </div> A full data model for each object in <code class="docutils literal notranslate">transparency_entries</code> is provided in <a class="reference internal" href="#appendix-2">Appendix 2: Data models for Transparency Log Entries</a>. Attestation objects SHOULD include one or more transparency log entries, and MAY include additional keys for other sources of signed time (such as an <a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc3161.html">RFC 3161</a> Time Stamping Authority or a <a class="reference external" href="https://blog.cloudflare.com/roughtime">Roughtime</a> server). Attestation objects are versioned; this PEP specifies version 1. Each version is tied to a single cryptographic suite to minimize unnecessary cryptographic agility. In version 1, the suite is as follows: <ul class="simple"> <li>Certificates are specified as X.509 certificates, and comply with the profile in <a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc5280.html">RFC 5280</a>.</li> <li>The message signature algorithm is ECDSA, with the P-256 curve for public keys and SHA-256 as the cryptographic digest function.</li> </ul> Future PEPs may change this suite (and the overall shape of the attestation object) by selecting a new version number. <section id="attestation-statement-and-signature-generation"> <h4><a class="toc-backref" href="#attestation-statement-and-signature-generation" role="doc-backlink">Attestation statement and signature generation</a></h4> The attestation statement is the actual claim that is cryptographically signed over within the attestation object (i.e., the <code class="docutils literal notranslate">envelope.statement</code>). The attestation statement is encoded as a <a class="reference external" href="https://github.com/in-toto/attestation/blob/v1.0/spec/v1.0/statement.md">v1 in-toto Statement object</a>, in JSON form. When serialized the statement is treated as an opaque binary blob, avoiding the need for canonicalization. An example JSON-encoded statement is provided in <a class="reference internal" href="#appendix-4">Appendix 4: Example attestation statement</a>. In addition to being a v1 in-toto Statement, the attestation statement is constrained in the following ways: <ul class="simple"> <li>The in-toto <code class="docutils literal notranslate">subject</code> MUST contain only a single subject.</li> <li><code class="docutils literal notranslate">subject[0].name</code> is the distribution’s filename, which MUST be a valid <a class="reference external" href="https://packaging.python.org/en/latest/specifications/source-distribution-format/#source-distribution-format" title="(in Python Packaging User Guide)">source distribution</a> or <a class="reference external" href="https://packaging.python.org/en/latest/specifications/binary-distribution-format/#binary-distribution-format" title="(in Python Packaging User Guide)">wheel distribution</a> filename.</li> <li><code class="docutils literal notranslate">subject[0].digest</code> MUST contain a SHA-256 digest. Other digests MAY be present. The digests MUST be represented as hexadecimal strings.</li> <li>The following <code class="docutils literal notranslate">predicateType</code> values are supported:<ul> <li><a class="reference external" href="https://slsa.dev/provenance/v1">SLSA Provenance</a>: <code class="docutils literal notranslate">https://slsa.dev/provenance/v1</code></li> <li><a class="reference external" href="https://docs.pypi.org/attestations/publish/v1">PyPI Publish Attestation</a>: <code class="docutils literal notranslate">https://docs.pypi.org/attestations/publish/v1</code></li> </ul> </li> </ul> The signature over this statement is constructed using the <a class="reference external" href="https://github.com/secure-systems-lab/dsse/blob/v1.0.0/protocol.md">v1 DSSE signature protocol</a>, with a <code class="docutils literal notranslate">PAYLOAD_TYPE</code> of <code class="docutils literal notranslate">application/vnd.in-toto+json</code> and a <code class="docutils literal notranslate">PAYLOAD_BODY</code> of the JSON-encoded statement above. No other <code class="docutils literal notranslate">PAYLOAD_TYPE</code> is permitted. </section> </section> <section id="provenance-objects"> <h3><a class="toc-backref" href="#provenance-objects" role="doc-backlink">Provenance objects</a></h3> The index will serve uploaded attestations along with metadata that can assist in verifying them in the form of JSON serialized objects. These provenance objects will be available via both the Simple Index and JSON-based Simple API as described above, and will have the following layout: <div class="highlight-json notranslate"><div class="highlight"><pre>{ "version": 1, "attestation_bundles": [ { "publisher": { "kind": "important-ci-service", "claims": {}, "vendor-property": "foo", "another-property": 123 }, "attestations": [ { /* attestation 1 ... */ }, { /* attestation 2 ... */ } ] } ] } </pre></div> </div> or, as pseudocode: <div class="highlight-python notranslate"><div class="highlight"><pre>@dataclass class Publisher: kind: string """ The kind of Trusted Publisher. """ claims: object | None """ Any context-specific claims retained by the index during Trusted Publisher authentication. """ _rest: object """ Each publisher object is open-ended, meaning that it MAY contain additional fields beyond the ones specified explicitly above. This field signals that, but is not itself present. """ @dataclass class AttestationBundle: publisher: Publisher """ The publisher associated with this set of attestations. """ attestations: list[Attestation] """ The set of attestations included in this bundle. """ @dataclass class Provenance: version: Literal[1] """ The provenance object's version, which is always 1. """ attestation_bundles: list[AttestationBundle] """ One or more attestation "bundles". """ </pre></div> </div> <ul> <li><code class="docutils literal notranslate">version</code> is <code class="docutils literal notranslate">1</code>. Like attestation objects, provenance objects are versioned, and this PEP only defines version <code class="docutils literal notranslate">1</code>.</li> <li><code class="docutils literal notranslate">attestation_bundles</code> is a required JSON array, containing one or more “bundles” of attestations. Each bundle corresponds to a signing identity (such as a Trusted Publishing identity), and contains one or more attestation objects.As noted in the <code class="docutils literal notranslate">Publisher</code> model, each <code class="docutils literal notranslate">AttestationBundle.publisher</code> object is specific to its Trusted Publisher but must include at minimum: <ul class="simple"> <li>A <code class="docutils literal notranslate">kind</code> key, which MUST be a JSON string that uniquely identifies the kind of Trusted Publisher.</li> <li>A <code class="docutils literal notranslate">claims</code> key, which MUST be a JSON object containing any context-specific claims retained by the index during Trusted Publisher authentication.</li> </ul> All other keys in the publisher object are publisher-specific. A full illustrative example of a publisher object is provided in <a class="reference internal" href="#appendix-1">Appendix 1: Example Trusted Publisher Representation</a>. Each array of attestation objects is a superset of the <code class="docutils literal notranslate">attestations</code> array supplied by the uploaded through the <code class="docutils literal notranslate">attestations</code> field at upload time, as described in <a class="reference internal" href="#upload-endpoint">Upload endpoint changes</a> and <a class="reference internal" href="#changes-to-provenance-objects">Changes to provenance objects</a>. </li> </ul> <section id="changes-to-provenance-objects"> <h4><a class="toc-backref" href="#changes-to-provenance-objects" role="doc-backlink">Changes to provenance objects</a></h4> Provenance objects are not immutable, and may change over time. Reasons for changes to the provenance object include but are not limited to: <ul class="simple"> <li>Addition of new attestations for a pre-existing signing identity: the index MAY choose to allow additional attestations by pre-existing signing identities, such as newer attestation versions for already uploaded files.</li> <li>Addition of new signing identities and associated attestations: the index MAY choose to support attestations from sources other than the file’s uploader, such as third-party auditors or the index itself. These attestations may be performed asynchronously, requiring the index to insert them into the provenance object post facto.</li> </ul> </section> </section> <section id="attestation-verification"> <h3><a class="toc-backref" href="#attestation-verification" role="doc-backlink">Attestation verification</a></h3> Verifying an attestation object against a distribution file requires verification of each of the following: <ul class="simple"> <li><code class="docutils literal notranslate">version</code> is <code class="docutils literal notranslate">1</code>. The verifier MUST reject any other version.</li> <li><code class="docutils literal notranslate">verification_material.certificate</code> is a valid signing certificate, as issued by an a priori trusted authority (such as a root of trust already present within the verifying client).</li> <li><code class="docutils literal notranslate">verification_material.certificate</code> identifies an appropriate signing subject, such as the machine identity of the Trusted Publisher that published the package.</li> <li><code class="docutils literal notranslate">envelope.statement</code> is a valid in-toto v1 Statement, with a subject and digest that MUST match the distribution’s filename and contents. For the distribution’s filename, matching MUST be performed by parsing using the appropriate source distribution or wheel filename format, as the statement’s subject may be equivalent but normalized.</li> <li><code class="docutils literal notranslate">envelope.signature</code> is a valid signature for <code class="docutils literal notranslate">envelope.statement</code> corresponding to <code class="docutils literal notranslate">verification_material.certificate</code>, as reconstituted via the <a class="reference external" href="https://github.com/secure-systems-lab/dsse/blob/v1.0.0/protocol.md">v1 DSSE signature protocol</a>.</li> </ul> In addition to the above required steps, a verifier MAY additionally verify <code class="docutils literal notranslate">verification_material.transparency_entries</code> on a policy basis, e.g. requiring at least one transparency log entry or a threshold of entries. When verifying transparency entries, the verifier MUST confirm that the inclusion time for each entry lies within the signing certificate’s validity period. </section> </section> <section id="security-implications"> <h2><a class="toc-backref" href="#security-implications" role="doc-backlink">Security Implications</a></h2> This PEP is primarily “mechanical” in nature; it provides layouts for structuring and serving verifiable digital attestations without specifying higher level security “policies” around attestation validity, thresholds between attestations, and so forth. <section id="cryptographic-agility-in-attestations"> <h3><a class="toc-backref" href="#cryptographic-agility-in-attestations" role="doc-backlink">Cryptographic agility in attestations</a></h3> Algorithmic agility is a common source of exploitable vulnerabilities in cryptographic schemes. This PEP limits algorithmic agility in two ways: <ul class="simple"> <li>All algorithms are specified in a single suite, rather than a geometric collection of parameters. This makes it impossible (for example) for an attacker to select a strong signature algorithm with a weak hash function, compromising the scheme as a whole.</li> <li>Attestation objects are versioned, and may only contain the algorithmic suite specified for their version. If a specific suite is considered insecure in the future, clients may choose to blanket reject or qualify verifications of attestations that contain that suite.</li> </ul> </section> <section id="index-trust"> <h3><a class="toc-backref" href="#index-trust" role="doc-backlink">Index trust</a></h3> This PEP does not increase (or decrease) trust in the index itself: the index is still effectively trusted to honestly deliver unmodified package distributions, since a dishonest index capable of modifying package contents could also dishonestly modify or omit package attestations. As a result, this PEP’s presumption of index trust is equivalent to the unstated presumption with earlier mechanisms, like PGP and wheel signatures. This PEP does not preclude or exclude future index trust mechanisms, such as <a class="pep reference internal" href="../pep-0458/" title="PEP 458 – Secure PyPI downloads with signed repository metadata">PEP 458</a> and/or <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>. </section> </section> <section id="recommendations"> <h2><a class="toc-backref" href="#recommendations" role="doc-backlink">Recommendations</a></h2> This PEP recommends, but does not mandate, that attestation objects contain one or more verifiable sources of signed time that corroborate the signing certificate’s claimed validity period. Indices that implement this PEP may choose to strictly enforce this requirement. </section> <section id="appendix-1-example-trusted-publisher-representation"> <h2><a class="toc-backref" href="#appendix-1-example-trusted-publisher-representation" role="doc-backlink">Appendix 1: Example Trusted Publisher Representation</a></h2> This appendix provides a fictional example of a <code class="docutils literal notranslate">publisher</code> key within a simple JSON API <code class="docutils literal notranslate">project.files[].provenance</code> listing: <div class="highlight-json notranslate"><div class="highlight"><pre>"publisher": { "kind": "GitHub", "claims": { "ref": "refs/tags/v1.0.0", "sha": "da39a3ee5e6b4b0d3255bfef95601890afd80709" }, "repository_name": "HolyGrail", "repository_owner": "octocat", "repository_owner_id": "1", "workflow_filename": "publish.yml", "environment": null } </pre></div> </div> </section> <section id="appendix-2-data-models-for-transparency-log-entries"> <h2><a class="toc-backref" href="#appendix-2-data-models-for-transparency-log-entries" role="doc-backlink">Appendix 2: Data models for Transparency Log Entries</a></h2> This appendix contains pseudocoded data models for transparency log entries in attestation objects. Each transparency log entry serves as a source of signed inclusion time, and can be verified either online or offline. <div class="highlight-python notranslate"><div class="highlight"><pre>@dataclass class TransparencyLogEntry: log_index: int """ The global index of the log entry, used when querying the log. """ log_id: str """ An opaque, unique identifier for the log. """ entry_kind: str """ The kind (type) of log entry. """ entry_version: str """ The version of the log entry's submitted format. """ integrated_time: int """ The UNIX timestamp from the log from when the entry was persisted. """ inclusion_proof: InclusionProof """ The actual inclusion proof of the log entry. """ @dataclass class InclusionProof: log_index: int """ The index of the entry in the tree it was written to. """ root_hash: str """ The digest stored at the root of the Merkle tree at the time of proof generation. """ tree_size: int """ The size of the Merkle tree at the time of proof generation. """ hashes: list[str] """ A list of hashes required to complete the inclusion proof, sorted in order from leaf to root. The leaf and root hashes are not themselves included in this list; the root is supplied via `root_hash` and the client must calculate the leaf hash. """ checkpoint: str """ The signed tree head's signature, at the time of proof generation. """ cosigned_checkpoints: list[str] """ Cosigned checkpoints from zero or more log witnesses. """ </pre></div> </div> </section> <section id="appendix-3-simple-json-api-size-considerations"> <h2><a class="toc-backref" href="#appendix-3-simple-json-api-size-considerations" role="doc-backlink">Appendix 3: Simple JSON API size considerations</a></h2> A previous draft of this PEP required embedding each <a class="reference internal" href="#provenance-object">provenance object</a> directly into its appropriate part of the JSON Simple API. The current version of this PEP embeds the SHA-256 digest of the provenance object instead. This is done for size and network bandwidth consideration reasons: <ol class="arabic simple"> <li>We estimate the typical size of an attestation object to be approximately 5.3 KB of JSON.</li> <li>We conservatively estimate that indices eventually host around 3 attestations per release file, or approximately 15.9 KB of JSON per combined provenance object.</li> <li>As of May 2024, the average project on PyPI has approximately 21 release files. We conservatively expect this average to increase over time.</li> <li>Combined, these numbers imply that a typical project might expect to host between 60 and 70 attestations, or approximately 339 KB of additional JSON in its “project detail” endpoint.</li> </ol> These numbers are significantly worse in “pathological” cases, where projects have hundreds or thousands of releases and/or dozens of files per release. </section> <section id="appendix-4-example-attestation-statement"> <h2><a class="toc-backref" href="#appendix-4-example-attestation-statement" role="doc-backlink">Appendix 4: Example attestation statement</a></h2> Given a source distribution <code class="docutils literal notranslate">sampleproject-1.2.3.tar.gz</code> with a SHA-256 digest of <code class="docutils literal notranslate">e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855</code>, the following is an appropriate in-toto Statement, as a JSON object: <div class="highlight-json notranslate"><div class="highlight"><pre>{ "_type": "https://in-toto.io/Statement/v1", "subject": [ { "name": "sampleproject-1.2.3.tar.gz", "digest": {"sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"} } ], "predicateType": "https://some-arbitrary-predicate.example.com/v1", "predicate": { "something-else": "foo" } } </pre></div> </div> </section> <section id="copyright"> <h2><a class="toc-backref" href="#copyright" role="doc-backlink">Copyright</a></h2> This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive. </section> </section> <hr class="docutils" /> Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-0740.rst">https://github.com/python/peps/blob/main/peps/pep-0740.rst</a> Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0740.rst">2024-09-27 00:47:01 GMT</a> </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="#rationale-and-motivation">Rationale and Motivation</a><ul> <li><a class="reference internal" href="#design-considerations">Design Considerations</a></li> <li><a class="reference internal" href="#previous-work">Previous Work</a><ul> <li><a class="reference internal" href="#pgp-signatures">PGP signatures</a></li> <li><a class="reference internal" href="#wheel-signatures">Wheel signatures</a></li> </ul> </li> </ul> </li> <li><a class="reference internal" href="#specification">Specification</a><ul> <li><a class="reference internal" href="#upload-endpoint-changes">Upload endpoint changes</a></li> <li><a class="reference internal" href="#index-changes">Index changes</a><ul> <li><a class="reference internal" href="#simple-index">Simple Index</a></li> <li><a class="reference internal" href="#json-based-simple-api">JSON-based Simple API</a></li> </ul> </li> <li><a class="reference internal" href="#attestation-objects">Attestation objects</a><ul> <li><a class="reference internal" href="#attestation-statement-and-signature-generation">Attestation statement and signature generation</a></li> </ul> </li> <li><a class="reference internal" href="#provenance-objects">Provenance objects</a><ul> <li><a class="reference internal" href="#changes-to-provenance-objects">Changes to provenance objects</a></li> </ul> </li> <li><a class="reference internal" href="#attestation-verification">Attestation verification</a></li> </ul> </li> <li><a class="reference internal" href="#security-implications">Security Implications</a><ul> <li><a class="reference internal" href="#cryptographic-agility-in-attestations">Cryptographic agility in attestations</a></li> <li><a class="reference internal" href="#index-trust">Index trust</a></li> </ul> </li> <li><a class="reference internal" href="#recommendations">Recommendations</a></li> <li><a class="reference internal" href="#appendix-1-example-trusted-publisher-representation">Appendix 1: Example Trusted Publisher Representation</a></li> <li><a class="reference internal" href="#appendix-2-data-models-for-transparency-log-entries">Appendix 2: Data models for Transparency Log Entries</a></li> <li><a class="reference internal" href="#appendix-3-simple-json-api-size-considerations">Appendix 3: Simple JSON API size considerations</a></li> <li><a class="reference internal" href="#appendix-4-example-attestation-statement">Appendix 4: Example attestation statement</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> <a id="source" href="https://github.com/python/peps/blob/main/peps/pep-0740.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>