diff --git a/source/specifications/index-hosted-attestations.rst b/source/specifications/index-hosted-attestations.rst index d078e87bd..c04223c5d 100644 --- a/source/specifications/index-hosted-attestations.rst +++ b/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 `__ 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