From 78fdf202a2d82ea5d3a558a8c8e369e1f113ec8a Mon Sep 17 00:00:00 2001 From: Jussi Kukkonen Date: Tue, 21 Oct 2025 14:02:21 +0300 Subject: [PATCH 1/7] Index hosted attestations: Add optional timestamps Sigstore public good instance is transitioning to Rekor v2 transparency log: This log no longer includes integrated time in the log entries and external timestamps are then needed. --- source/specifications/index-hosted-attestations.rst | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/source/specifications/index-hosted-attestations.rst b/source/specifications/index-hosted-attestations.rst index d078e87bd..fce8e81bd 100644 --- a/source/specifications/index-hosted-attestations.rst +++ b/source/specifications/index-hosted-attestations.rst @@ -85,6 +85,13 @@ object is provided as pseudocode below. and certificate. """ + timestamps: list[bytes] | None + """ + Optional list of base64 encoded RFC3161 timestamp responses. Timestamps + are optional if `transparency_entries` only contains entries with an + integrated_time. + """ + A full data model for each object in ``transparency_entries`` is provided in :ref:`appendix`. Attestation objects **SHOULD** include one or more transparency log entries, and **MAY** include additional keys for other @@ -285,7 +292,9 @@ In addition to the above required steps, a verifier **MAY** additionally verify ``verification_material.transparency_entries`` 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. +each entry lies within the signing certificate's validity period: Inclusion time +is either embedded in the entry (``integrated_time``) or provided as RFC3161 +timestamp in ``verification_material.timestamps``. .. _appendix: From 518d607625426e6fa82c2055af22cf99f796eabb Mon Sep 17 00:00:00 2001 From: Jussi Kukkonen Date: Wed, 29 Oct 2025 15:41:30 +0200 Subject: [PATCH 2/7] index hosted attestations: Add detail about timestamps I'm trying to not include too much detail here as the doc already states that entry verification depends on policy... but dsse 0.0.1 is the rekor v1 entry type used in the attestations so maybe this works? --- source/specifications/index-hosted-attestations.rst | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/source/specifications/index-hosted-attestations.rst b/source/specifications/index-hosted-attestations.rst index fce8e81bd..586930f80 100644 --- a/source/specifications/index-hosted-attestations.rst +++ b/source/specifications/index-hosted-attestations.rst @@ -291,10 +291,12 @@ following: In addition to the above required steps, a verifier **MAY** additionally verify ``verification_material.transparency_entries`` 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: Inclusion time -is either embedded in the entry (``integrated_time``) or provided as RFC3161 -timestamp in ``verification_material.timestamps``. +transparency entries, the verifier **MUST** confirm that the entry inclusion time +lies within the signing certificate's validity period: Inclusion time is provided +in one of two ways: +* embedded in the entry (``integrated_time``) -- this is *only* valid for + entry kind ``dsse 0.0.1`` +* as RFC3161 timestamp(s) in ``verification_material.timestamps`` .. _appendix: From c5409ddb2e6ed8f26541853f3292941fd49c0aea Mon Sep 17 00:00:00 2001 From: Jussi Kukkonen Date: Wed, 29 Oct 2025 15:47:40 +0200 Subject: [PATCH 3/7] index hosted attestations: Make timestamps not optional --- source/specifications/index-hosted-attestations.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/source/specifications/index-hosted-attestations.rst b/source/specifications/index-hosted-attestations.rst index 586930f80..ad563e924 100644 --- a/source/specifications/index-hosted-attestations.rst +++ b/source/specifications/index-hosted-attestations.rst @@ -85,11 +85,11 @@ object is provided as pseudocode below. and certificate. """ - timestamps: list[bytes] | None + timestamps: list[bytes] """ - Optional list of base64 encoded RFC3161 timestamp responses. Timestamps - are optional if `transparency_entries` only contains entries with an - integrated_time. + List of base64 encoded RFC3161 timestamp responses. Note that list + may be empty if `transparency_entries` only contains entries with an + integrated_time (in other words entries of kind "dsse 0.0.1"). """ A full data model for each object in ``transparency_entries`` is provided in From c89ce14c57f9e55aeb050853f9e99a9593d3f6ef Mon Sep 17 00:00:00 2001 From: Jussi Kukkonen Date: Mon, 3 Nov 2025 13:52:10 +0200 Subject: [PATCH 4/7] index hosted attestations: Increase version number --- .../index-hosted-attestations.rst | 22 ++++++++++++++----- 1 file changed, 16 insertions(+), 6 deletions(-) diff --git a/source/specifications/index-hosted-attestations.rst b/source/specifications/index-hosted-attestations.rst index ad563e924..520b28692 100644 --- a/source/specifications/index-hosted-attestations.rst +++ b/source/specifications/index-hosted-attestations.rst @@ -43,7 +43,10 @@ object is provided as pseudocode below. class Attestation: version: Literal[1] """ - The attestation object's version, which is always 1. + The attestation object's version. Current version is 2. + + version 2 added verification_material.timestamps, in practice allowing the + use of rekor v2 entries in verification_material.transparency_entries. """ verification_material: VerificationMaterial @@ -87,9 +90,12 @@ object is provided as pseudocode below. timestamps: list[bytes] """ - List of base64 encoded RFC3161 timestamp responses. Note that list - may be empty if `transparency_entries` only contains entries with an - integrated_time (in other words entries of kind "dsse 0.0.1"). + List of base64 encoded RFC3161 timestamp responses. + + Added in Attestation version 2. + + Note that list may be empty if `transparency_entries` only contains entries + with an integrated_time (in other words entries of kind "dsse 0.0.1"). """ A full data model for each object in ``transparency_entries`` is provided in @@ -98,9 +104,9 @@ transparency log entries, and **MAY** include additional keys for other sources of signed time (such as an :rfc:`3161` Time Stamping Authority or a `Roughtime `__ server). -Attestation objects are versioned; this PEP specifies version 1. Each version +Attestation objects are versioned; this PEP specifies version 2. Each version is tied to a single cryptographic suite to minimize unnecessary cryptographic -agility. In version 1, the suite is as follows: +agility. In both versions 1 & 2, the suite is as follows: * Certificates are specified as X.509 certificates, and comply with the profile in :rfc:`5280`. @@ -334,6 +340,10 @@ of signed inclusion time, and can be verified either online or offline. integrated_time: int """ The UNIX timestamp from the log from when the entry was persisted. + + Note: An integrated timestamp is not always provided (in practice + integrated_time == 0 in this case): in this case external + Timestamp Authority timestamps are required to verify the entry. """ inclusion_proof: InclusionProof From 85c5efaac5003208695afae21cd618a46f6660c6 Mon Sep 17 00:00:00 2001 From: Jussi Kukkonen Date: Wed, 3 Dec 2025 15:43:18 +0200 Subject: [PATCH 5/7] index-hosted-attestations: Try to make linter happy --- source/specifications/index-hosted-attestations.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/source/specifications/index-hosted-attestations.rst b/source/specifications/index-hosted-attestations.rst index 520b28692..151abf4af 100644 --- a/source/specifications/index-hosted-attestations.rst +++ b/source/specifications/index-hosted-attestations.rst @@ -300,8 +300,9 @@ at least one transparency log entry or a threshold of entries. When verifying transparency entries, the verifier **MUST** confirm that the entry inclusion time lies within the signing certificate's validity period: Inclusion time is provided in one of two ways: -* embedded in the entry (``integrated_time``) -- this is *only* valid for - entry kind ``dsse 0.0.1`` + +* embedded in the entry (``integrated_time``) -- this is *only* valid for entry + kind ``dsse 0.0.1``. * as RFC3161 timestamp(s) in ``verification_material.timestamps`` .. _appendix: From 4f87c8de76afb44ac3a883e8dd63fa4ba2f86cfc Mon Sep 17 00:00:00 2001 From: Jussi Kukkonen Date: Mon, 8 Dec 2025 18:04:37 +0200 Subject: [PATCH 6/7] index hosted attestations: improve language over version --- .../index-hosted-attestations.rst | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/source/specifications/index-hosted-attestations.rst b/source/specifications/index-hosted-attestations.rst index 151abf4af..b0621c5d3 100644 --- a/source/specifications/index-hosted-attestations.rst +++ b/source/specifications/index-hosted-attestations.rst @@ -39,9 +39,10 @@ object is provided as pseudocode below. .. code-block:: python + @dataclass class Attestation: - version: Literal[1] + version: Literal[1, 2] """ The attestation object's version. Current version is 2. @@ -94,8 +95,7 @@ object is provided as pseudocode below. Added in Attestation version 2. - Note that list may be empty if `transparency_entries` only contains entries - with an integrated_time (in other words entries of kind "dsse 0.0.1"). + Note that list may be empty even for valid attestations: see "Attestation Verification" """ A full data model for each object in ``transparency_entries`` is provided in @@ -104,7 +104,7 @@ transparency log entries, and **MAY** include additional keys for other sources of signed time (such as an :rfc:`3161` Time Stamping Authority or a `Roughtime `__ server). -Attestation objects are versioned; this PEP specifies version 2. Each version +Attestation objects are versioned; this document specifies version 2. Each version is tied to a single cryptographic suite to minimize unnecessary cryptographic agility. In both versions 1 & 2, the suite is as follows: @@ -277,7 +277,7 @@ Attestation verification Verifying an attestation object against a distribution file requires verification of each of the following: -* ``version`` is ``1``. The verifier **MUST** reject any other version. +* ``version`` is ``1`` or ``2``. The verifier **MUST** reject any other version. * ``verification_material.certificate`` 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). @@ -301,9 +301,10 @@ transparency entries, the verifier **MUST** confirm that the entry inclusion tim lies within the signing certificate's validity period: Inclusion time is provided in one of two ways: -* embedded in the entry (``integrated_time``) -- this is *only* valid for entry - kind ``dsse 0.0.1``. -* as RFC3161 timestamp(s) in ``verification_material.timestamps`` +* Attestation V1: Inclusion time is embedded in the entry (``integrated_time``) +* Attestation V2: Inclusion time may embedded in the entry (``integrated_time``) for dsse 0.0.1 entries + or it may be provided as RFC3161 timestamp(s) in ``verification_material.timestamps`` for + dsse 0.0.2 entries .. _appendix: From 49eafc2c6e339c69d56c29ecd1d681459fd97b2c Mon Sep 17 00:00:00 2001 From: Jussi Kukkonen Date: Mon, 8 Dec 2025 18:27:23 +0200 Subject: [PATCH 7/7] index hosted attestations: Try to model both versions at same time It's not very pretty but maybe it is now more comprehensive? --- .../index-hosted-attestations.rst | 38 ++++++++++++++----- 1 file changed, 28 insertions(+), 10 deletions(-) diff --git a/source/specifications/index-hosted-attestations.rst b/source/specifications/index-hosted-attestations.rst index b0621c5d3..c04223c5d 100644 --- a/source/specifications/index-hosted-attestations.rst +++ b/source/specifications/index-hosted-attestations.rst @@ -39,15 +39,13 @@ object is provided as pseudocode below. .. code-block:: python + Attestation = AttestationV1 | AttestationV2 @dataclass - class Attestation: - version: Literal[1, 2] + class AttestationV1: + version: Literal[1] """ - The attestation object's version. Current version is 2. - - version 2 added verification_material.timestamps, in practice allowing the - use of rekor v2 entries in verification_material.transparency_entries. + The attestation object's version. """ verification_material: VerificationMaterial @@ -60,6 +58,23 @@ object is provided as pseudocode below. The enveloped attestation statement and signature. """ + @dataclass + class AttestationV2: + version: Literal[2] + """ + The attestation object's version. + """ + + verification_material: VerificationMaterialV2 + """ + Cryptographic materials used to verify `envelope`. + """ + + envelope: Envelope + """ + The enveloped attestation statement and signature. + """ + @dataclass class Envelope: @@ -89,13 +104,16 @@ object is provided as pseudocode below. and certificate. """ + @dataclass + class VerificationMaterialV2(VerificationMaterial): timestamps: list[bytes] """ List of base64 encoded RFC3161 timestamp responses. - Added in Attestation version 2. + Added in V2. In practice this allows the use of dsse 0.0.2 entries (used in Rekor v2 + transparency log) within VerificationMaterialV2.transparency_entries. - Note that list may be empty even for valid attestations: see "Attestation Verification" + Note that list may be empty when dsse 0.0.1 entries are used: see "Attestation Verification" """ A full data model for each object in ``transparency_entries`` is provided in @@ -302,9 +320,9 @@ lies within the signing certificate's validity period: Inclusion time is provide in one of two ways: * Attestation V1: Inclusion time is embedded in the entry (``integrated_time``) -* Attestation V2: Inclusion time may embedded in the entry (``integrated_time``) for dsse 0.0.1 entries +* Attestation V2: Inclusion time may embedded in the entry (``integrated_time``) for "dsse 0.0.1" entries or it may be provided as RFC3161 timestamp(s) in ``verification_material.timestamps`` for - dsse 0.0.2 entries + "dsse 0.0.2" entries .. _appendix: