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,61 @@
 
 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_ an attestation without being detected.
+Predicates that follow [the monotonic principle] should not have any issues
+with this behavior.
 
 ## 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 a different signing key,
     `_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].
+-   Each [Envelope] within a Bundle MAY use a different signature format,
+    but it MUST fit on a single JSON line.
+-   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 encoding of the Bundle contents MAY be omitted from its media type
+    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 +83,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.
 

spec/v1/envelope.md

@@ -7,7 +7,9 @@ authentication and serialization.
 
 ## Schema
 
-The format and protocol are defined per [DSSE v1.0].
+The RECOMMENDED format and protocol for Envelopes are defined per [DSSE v1.0].
+Producers MAY use other signature methods and formats so long as they meet
+the [Bundle] data structure requirements.
 
 ## Fields
 
@@ -19,5 +21,41 @@ standard DSSE fields.
     specifying its schema.
 -   `payload` MUST be a base64-encoded JSON [Statement].
 
+## File naming convention
+
+Envelopes SHOULD use the suffix `.json`.
+
+-   An Envelope containing an attestation about a particular SW supply chain
+    step `<step-name>` SHOULD be named `<step-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 hash of the public key `<pubkey-hash>` of the signing
+    functionary: `<step-name>.<pubkey-hash>.json`.
+
+## Storage convention
+
+The media type `application/vnd.in-toto.<predicate>+<sig>` 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.
+-   The `<sig>` MUST be a succint alias that unambiguously identifies
+    the Envelope signature format.
+-   Consumers SHOULD NOT rely upon the media type for individual attestations
+    as faithful indicators of predicate type because this information is only
+    authenticated at the [Statement] layer.
+-   To obtain predicate information that is authenticated, consumers MUST
+    parse the Envelope's `payload`.
+
+### Example
+
+The media type for a single DSSE-signed attestation containing an
+[SPDX predicate] SHOULD be `application/vnd.in-toto.spdx+dsse`.
+
+[Bundle]: bundle.md
 [DSSE v1.0]: https://github.com/secure-systems-lab/dsse/blob/v1.0.0/envelope.md
+[SPDX predicate]: ../predicates/spdx.md
 [Statement]: statement.md
+[functionaries]: https://github.com/in-toto/docs/blob/v1.0/in-toto-spec.md#212-functionaries
+[predicate specification name]: ../predicates