Merge pull request #283 from marcelamelara/clarify-layers-media-type

Clarify specification on Bundle and Envelope media types

spec/README.md

@@ -24,12 +24,19 @@ The source of this diagram can be found [here](../images/envelope_relationships.
 The [validation model] provides pseudocode showing how these layers fit
 together. See the [documentation] for more background and examples.
 
+## Keywords
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
+"SHOULD NOT", "RECOMMENDED",  "MAY", and "OPTIONAL" in all documents under
+this specification are to be interpreted as described in [RFC 2119].
+
 [^1]: This is compatible with the [SLSA Attestation Model].
 
 [Binary Authorization]: https://cloud.google.com/binary-authorization
 [Bundle]: v1/bundle.md
 [Envelope]: v1/envelope.md
 [Predicate]: v1/predicate.md
+[RFC 2119]: https://www.rfc-editor.org/rfc/rfc2119
 [SLSA Attestation Model]: https://slsa.dev/attestation-model
 [Statement]: v1/statement.md
 [documentation]: ../docs

spec/v1/bundle.md

@@ -2,40 +2,62 @@
 
 Version: v1.0
 
-An attestation bundle is a collection of multiple attestations in a single
+An attestation Bundle is a collection of multiple attestations in a single
 file. This allows attestations from multiple different points in the software
 supply chain (e.g. Provenance, Code Review, Test Result, vuln scan, ...) to
 be grouped together, allowing users to make decisions based on all available
 information.
 
-**NOTE**: The bundle is not authenticated as a whole. Instead each individual
-attestation is authenticated using [DSSE]. As such, an attacker might be able
-to _delete_ an attestation without being detected. Predicates that follow
-[the monotonic principle] should not have any issues with this behavior.
+**NOTE**: The Bundle is not authenticated as a whole. Instead each individual
+attestation is authenticated using signature formats like [DSSE]. As such,
+an attacker might be able to delete valid attestations, replay obsolete
+attestations, and/or inject invalid or irrelevant attestations in a Bundle
+without being detected.
+
+Our Bundle specification aims to reduce the risks of such attacks.
+In addition, predicates that follow the [monotonic principle] should not
+have any issues with deletion attacks.
 
 ## Data structure
 
 Attestation Bundles use [JSON Lines] to store multiple attestations.
 
--   Each attestation within a bundle MAY have a different signing key,
+-   Each attestation within a Bundle MAY have different signing keys,
     `_type`, `subject`, and/or `predicateType`.
--   Each line SHOULD be an [Envelope]. Consumers MUST ignore unrecognized
-    lines.
+-   Each line within a Bundle SHOULD be an [Envelope]. Consumers MUST ignore
+    unrecognized lines.
 -   Consumers MUST ignore attestations with unrecognized keys, types,
     subjects, or predicates.
--   Processing of a bundle MUST NOT depend on the order of the attestations.
+-   Processing of a Bundle MUST NOT depend on the order of the attestations.
 
 ## File naming convention
 
 Bundles SHOULD use the suffix `.intoto.jsonl`.
 
-A bundle of attestations relevant for `<filename>` SHOULD be named
-`<filename>.intoto.jsonl`. Attestations in the bundle MAY have different
-subjects, but they SHOULD all be relevant to that file or its dependencies.
-For example, a package named `foo-1.2.3.tar.gz` with hash `abcd` that was
-built from git commit `1234` could have a bundle name
-`foo-1.2.3.tar.gz.intoto.jsonl` with two attestations, one with subject
-`abcd` and one with subject `1234`.
+-   A Bundle of attestations relevant for `<filename>` SHOULD be named
+    `<filename>.intoto.jsonl`.
+-   Attestations in the Bundle MAY have different subjects, but they SHOULD
+    all be relevant to that file or its dependencies.
+
+### Example
+
+A package named `foo-1.2.3.tar.gz` with hash `abcd` that was built from git
+commit `1234` could have a Bundle name `foo-1.2.3.tar.gz.intoto.jsonl` with
+two attestations, one with subject `abcd` and one with subject `1234`.
+
+## Storage convention
+
+The media type `application/vnd.in-toto.bundle` SHOULD be used to denote
+a Bundle in arbitrary storage systems.
+
+-   The media type for a Bundles does not indicate an encoding since Bundles
+    MUST be encoded as JSON lines, and the encoding of each attestation
+    within the Bundle SHOULD be indicated at the [Envelope] layer.
+-   The predicate type of individual attestations within the stored Bundle
+    SHOULD NOT be indicated in the media type for the Bundle, as this
+    information is not authenticated at the Bundle layer.
+-   To obtain predicate information that is authenticated, consumers MUST
+    download and parse each line in a Bundle separately.
 
 ## Example use case
 
@@ -62,7 +84,7 @@ places _both_ of these signed attestations in a new file named
 The CI/CD system then requests a third-party vulnerability scan on
 `fooly.apk`. The vulnerability scanner doesn't use in-toto Statements but
 instead uses their own custom `payloadType=application/vnd.novulz+cbor`,
-which they put in a DSSE envelope. This attestation indicates `fooly.apk`
+which they put in a [DSSE] envelope. This attestation indicates `fooly.apk`
 with hash `aaa...` has 0 critical vulnerabilities and 3 medium
 vulnerabilities.
 
@@ -147,3 +169,4 @@ $ grep . ~/multiple.intoto.jsonl | jq
 [Envelope]: envelope.md
 [JSON Lines]: https://jsonlines.org/
 [SLSA Provenance]: https://slsa.dev/provenance
+[monotonic principle]: https://github.com/in-toto/attestation/tree/main/spec/v1#parsing-rules

spec/v1/envelope.md

@@ -19,5 +19,48 @@ standard DSSE fields.
     specifying its schema.
 -   `payload` MUST be a base64-encoded JSON [Statement].
 
+## File naming convention
+
+If stored in a dedicated file by itself, and not as part of a [Bundle], an
+Envelope SHOULD use the suffix `.json`.
+
+-   For attestations intended for consumption by [in-toto-verify], an
+    Envelope containing an attestation about a particular software supply
+    chain step `<step-name>` SHOULD be named `<step-name>.json`.
+-   For other verifiers, or cases in which a step name cannot be easily
+    determined, the attestation producer and consumer MAY agree on an
+    arbitrary filename: `<env-name>.json`.
+-   If multiple Envelopes are produced for the same step by different
+    [functionaries] uniquely identified by a public key, an Envelope name
+    SHOULD include the truncated [KEYID] of the public key `<keyid[0:8]>` of
+    the signing functionary: `<step/env-name>.<keyid[0:8]>.json`.
+
+## Storage convention
+
+The media type `application/vnd.in-toto.<predicate>+dsse` SHOULD
+be used to denote an individual attestation in arbitrary storage systems.
+
+-   The `<predicate>` MUST match the [predicate specification name]
+    without the file extension. Predicate versioning is handled in the
+    [Statement] layer.
+-   Consumers SHOULD NOT rely upon the media type for individual attestations
+    as faithful indicators of predicate type. Consumer SHOULD only rely on the
+    `predicateType` field in the [Statement] layer.
+-   To obtain predicate information that is authenticated, consumers MUST
+    parse the Envelope's `payload`, and verify it against its `signatures`.
+
+### Examples
+
+Example media types for single DSSE-signed attestation predicates include:
+
+-   SLSA Provenance: `application/vnd.in-toto.provenance+dsse`
+-   SPDX: `application/vnd.in-toto.spdx+dsse`
+-   VSA: `application/vnd.in-toto.vsa+dsse`
+
+[Bundle]: bundle.md
 [DSSE v1.0]: https://github.com/secure-systems-lab/dsse/blob/v1.0.0/envelope.md
+[KEYID]: https://github.com/in-toto/docs/blob/v1.0/in-toto-spec.md#421-key-formats
 [Statement]: statement.md
+[in-toto-verify]: https://github.com/in-toto/in-toto#verification
+[functionaries]: https://github.com/in-toto/docs/blob/v1.0/in-toto-spec.md#212-functionaries
+[predicate specification name]: ../predicates