Define v0.3 of the link predicate

Updates materials to use list of ResourceDescriptor objects, introduces a protobuf
definition for the link predicate. Also adds predicate field definitions
alongside pointer to in-toto specification.

Signed-off-by: Aditya Sirish <[email protected]>

protos/README.md

@@ -15,6 +15,7 @@ predicates have protobuf definitions:
 
 -   [SLSA Verification Summary]: SLSA verification decision about a software
     artifact.
+-   [in-toto Link]: Generic predicate that records a software supply chain step
 
 ## Supported language bindings
 
@@ -41,6 +42,7 @@ Please read our protos [documentation] for instructions on building and
 testing the supported language bindings.
 
 [SLSA Verification Summary]: in_toto_attestation/predicates/vsa/
+[in-toto Link]: in_toto_attestation/predicates/link/
 [documentation]: ../docs/protos.md
 [go]: ../go/
 [python]: ../python/

protos/in_toto_attestation/predicates/link/v0/link.proto

@@ -0,0 +1,22 @@
+
+syntax = "proto3";
+
+package in_toto_attestation.predicates.link.v0;
+
+import "in_toto_attestation/v1/resource_descriptor.proto";
+import "google/protobuf/struct.proto";
+
+option go_package = "github.com/in-toto/attestation/go/predicates/link/v0";
+option java_package = "io.github.intoto.attestation.predicates.link.v0";
+
+message Link {
+    string name = 1;
+
+    repeated string command = 2;
+
+    repeated in_toto_attestation.v1.ResourceDescriptor materials = 3;
+
+    google.protobuf.Struct byproducts = 4;
+
+    google.protobuf.Struct environment = 5;
+}

spec/predicates/link.md

@@ -1,76 +1,137 @@
 # Predicate type: Link
 
-Type URI: https://in-toto.io/Link/v0.2
+Type URI: https://in-toto.io/attestation/link/v0.3
 
-Version: 0.2.0
+Deprecated Type URI: https://in-toto.io/Link/*
+
+Version: 0.3
 
 ## Purpose
 
-A generic attestation type with a schema isomorphic to [in-toto 0.9]. This
-allows existing in-toto users to make minimal changes to upgrade to the new
+A generic attestation type with a schema isomorphic to [in-toto specification].
+This allows existing in-toto users to make minimal changes to upgrade to the new
 attestation format.
 
-Most users should migrate to a more specific attestation type, such as
-[Provenance](provenance.md).
+Depending on the context, a more specific predicate type such as [Provenance]
+may be more appropriate.
+
+## Prerequisites
+
+Understanding of [in-toto specification] and the in-toto attestation framework.
+
+## Model
+
+Every link attestation corresponds to the execution of one step in the software
+supply chain. The `subject` field corresponds to the products of the operation
+while `materials` indicates the inputs to the step. The `name` field identifies
+the step the attestation corresponds to and the `command` field optionally
+describes the command that was run. Link attestations allow for recording
+arbitrary but relevant information in the opaque `environment` and `byproducts`
+fields.
+
+For every step described in the layout of the software supply chain, one (or
+more, depending on the threshold) signed link attestations must be presented.
 
 ## Schema
 
 ```jsonc
 {
   // Standard attestation fields:
-  "_type": "https://in-toto.io/Statement/v0.1",
+  "_type": "https://in-toto.io/Statement/v1",
   "subject": [{ ... }],
 
   // Predicate:
-  "predicateType": "https://in-toto.io/Link/v0.2",
+  "predicateType": "https://in-toto.io/attestation/link/v0.3",
   "predicate": {
     "name": "...",
-    "command": "...",
-    "materials": { ... },
+    "command": [ ... ],
+    "materials": [<ResourceDescriptor>, ...],
     "byproducts": { ... },
     "environment": { ... }
   }
 }
 ```
 
-_(Note: This is a Predicate type that fits within the larger
-[Attestation](../README.md) framework.)_
+### Fields
 
 The `predicate` has the same schema as the link's `signed` field in
-[in-toto 0.9] except:
+[in-toto specification] except:
 
--   `predicate._type` is omitted.  `predicateType` serves the same purpose.
+-   `predicate._type` is omitted. `predicateType` serves the same purpose.
 -   `predicate.products` is omitted. `subject` serves the same purpose.
+-   `predicate.materials` is updated to a list of `ResourceDescriptors`.
+    Each `ResourceDescriptor` entry MUST include `name` and `digest`.
+
+`name`, _string, required_
+
+Name of the step. When used with an in-toto layout as described in the
+[in-toto specification], this field is used when identifying link metadata to
+verify for a step.
+
+`command`, _list of strings, optional_
+
+Contains the command and its arguments executed during the step. While the field
+is required, it may be empty.
 
-## Converting to old-style links
+`materials`, _list of [ResourceDescriptor] objects, optional_
 
-A Link predicate may be converted into an in-toto 0.9 link as follows:
+List of artifacts that make up the materials of the step. The `name` and
+`digest` fields of each entry MUST be set. [ITE-4] artifact types may be
+identified using the `uri` or `mediaType` fields instead of overloading the
+`name` field.
 
--   Set `link` to be a copy of `predicate`.
--   Set `link.type` to `"link"`.
+`byproducts`, _object, optional_
+
+An opaque dictionary that contains additional information about the step
+performed. Consult the [in-toto specification] for how the verification workflow
+may use it.
+
+`environment`, _object, optional_
+
+An opaque dictionary that contains information about the environment in which
+the step was carried out. Consult the [in-toto specification] for how the
+verification workflow may use it.
+
+### Converting to old-style links
+
+A Link predicate may be converted into an [in-toto specification] link as
+follows:
+
+-   Set `link._type` to `"link"`.
+-   Set `link.name`, `link.environment`, and `link.byproducts` using
+    `predicate.name`, `predicate.environment`, and `predicate.byproducts`
+    respectively.
 -   Set `link.products` to be a map from `subject[*].name` to
     `subject[*].digest`.
+-   Set `link.materials` to be a map from `predicate.materials[*].name` to
+    `predicate.materials[*].digest`.
 
 In Python:
 
 ```python
 def convert(statement):
-    assert statement.predicateType == 'https://in-toto.io/Link/v0.2'
-    link = statement.predicate.copy()
+    assert statement.predicateType == 'https://in-toto.io/attestation/link/v0.3'
+    link = {}
     link['_type'] = 'link'
+    link['name'] = statement.predicate['name']
+    link['byproducts'] = statement.predicate['byproducts']
+    link['environment'] = statement.predicate['environment']
+    link['materials'] = {s['name'] : s['digest'] for s in statement.predicate['materials']}
     link['products'] = {s['name'] : s['digest'] for s in statement.subject}
     return link
 ```
 
-## TODO
-
--   [ ] Bump up the in-toto version from 0.9 to 1.0 once
-    [in-toto/docs issue #46](https://github.com/in-toto/docs/issues/46) is
-    resolved.
-
 ## Version History
 
+-   0.3: Updated `materials` to use a list of `ResourceDescriptor` objects.
+    Reverted `command` to a list of strings to match the original link
+    specification.
 -   0.2: Removed `_type` and `products`. Defined conversion rules.
--   0.1: Initial version.
+-   0.1: Initial version as described in [in-toto specification].
+
+<!-- TODO: Fix link-->
 
-[in-toto 0.9]: https://github.com/in-toto/docs/blob/master/in-toto-spec.md#44-file-formats-namekeyid-prefixlink
+[in-toto specification]: https://github.com/in-toto/docs/blob/master/in-toto-spec.md
+[ResourceDescriptor]: ../v1.0/resource_descriptor.md
+[Provenance]: provenance.md
+[ITE-4]: https://github.com/in-toto/ITE/blob/master/ITE/4/README.adoc

spec/v1.0/resource_descriptor.md

@@ -13,7 +13,7 @@ or immutable).
   "uri": "<RESOURCE URI>",
   "digest": { "<ALGORITHM>": "<HEX VALUE>", ... },
   "content": "<BASE64 VALUE>", // converted from bytes for JSON 
-  "downloadLocation": "<RESOURCE URI>"
+  "downloadLocation": "<RESOURCE URI>",
   "mediaType": "<MIME TYPE>",
   "annotations": {
     "<FIELD_1>": { /* object */ },