Index hosted attestations: Add optional timestamps

source/specifications/index-hosted-attestations.rst

@@ -39,11 +39,13 @@ object is provided as pseudocode below.
 
 .. code-block:: python
 
+  Attestation = AttestationV1 | AttestationV2
+
   @dataclass
-  class Attestation:
+  class AttestationV1:
       version: Literal[1]
       """
-      The attestation object's version, which is always 1.
+      The attestation object's version.
       """
 
       verification_material: VerificationMaterial
@@ -56,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:
@@ -85,15 +104,27 @@ object is provided as pseudocode below.
       and certificate.
       """
 
+  @dataclass
+  class VerificationMaterialV2(VerificationMaterial):
+      timestamps: list[bytes]
+      """
+      List of base64 encoded RFC3161 timestamp responses.
+
+      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 when dsse 0.0.1 entries are used: see "Attestation Verification"
+      """
+
 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
 sources of signed time (such as an :rfc:`3161` Time Stamping Authority or a
 `Roughtime <https://blog.cloudflare.com/roughtime>`__ server).
 
-Attestation objects are versioned; this PEP specifies version 1. 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 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`.
@@ -264,7 +295,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).
@@ -284,8 +315,14 @@ 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.
+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:
+
+* 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:
 
@@ -323,6 +360,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