diff --git a/docs/tr/endorsement_v1.md b/docs/tr/endorsement_v1.md index 722499d31f..1002ee5a9e 100644 --- a/docs/tr/endorsement_v1.md +++ b/docs/tr/endorsement_v1.md @@ -1,3 +1,84 @@ -# Endorsement V1 +# Endorsement Specification V1 -WIP: Landing page for endorsement V1 in-toto statement. +Transparent Release (TR) endorsement statements are represented and serialized +as [JSON] objects. + +## Schema + +Endorsements are [in-toto statement]s (V1 only) with a custom predicate. In the following +example, only the subject, the timestamps and the claim types are variable. + +```jsonc +{ + "_type": "https://in-toto.io/Statement/v1", + "subject": [ + { + "name": "oak_orchestrator", + "digest": { + "sha256": "8c938394c5962194d1449ee17b4db5fdf5a78729b38ebacf26de9bed4027e351", + }, + }, + ], + "predicateType": "https://project-oak.github.io/oak/tr/endorsement/v1", + "predicate": { + "issuedOn": "2024-10-07T06:44:22.459000Z", + "validity": { + "notBefore": "2024-10-07T06:44:22.459000Z", + "notAfter": "2025-10-07T06:44:22.459000Z", + }, + "claims": [ + { + "type": "https://github.com/project-oak/oak/blob/main/docs/tr/claim/85483.md", + }, + ], + }, +} +``` + +## Fields + +`_type` _string representing a [TypeURI], required_ + +> Identifier for the schema of the in-toto statement. Always +> `https://in-toto.io/Statement/v1` for the present endorsements. Only V1 +> in-toto statements are supported. + +`subject` _array of [ResourceDescriptor] objects, required_ + +> Fully follows the [in-toto statement] specification. + +`predicateType` _string representing a [TypeURI], required_ + +> Identifies the schema of the predicate. Always +> `https://project-oak.github.io/oak/tr/endorsement/v1` for the present +> endorsements. + +The `predicate` includes the following fields: + +`predicate.issuedOn` _string representing a [Timestamp], required_ + +> Specifies when the endorsement was issued. + +`predicate.validity.notBefore` _string representing a [Timestamp], required_ + +> Specifies when the endorsement starts to be valid. + +`predicate.validity.notAfter` _string representing a [Timestamp], required_ + +> Specifies when the endorsement ceases to be valid. + +`predicate.claims` _array of claim objects, optional_ + +> A claim identifies one or more properties the endorser asserts about the +> endorsed subject. Encoded claims have just one `type` field which is a string +> representing a [TypeURI]. The choice of identifier and its meaning are up to +> the endorser. + +[JSON]: https://www.json.org/json-en.html +[in-toto statement]: https://in-toto.io/Statement/v1 +[ResourceDescriptor]: + https://github.com/in-toto/attestation/blob/main/spec/v1/resource_descriptor.md +[TypeURI]: + https://github.com/in-toto/attestation/blob/main/spec/v1/field_types.md#TypeURI +[Timestamp]: + https://github.com/in-toto/attestation/blob/main/spec/v1/field_types.md#timestamp