Skip to content

Commit

Permalink
Add Reference field type
Browse files Browse the repository at this point in the history 
Signed-off-by: Marcela Melara <[email protected]>
  • Loading branch information
@marcelamelara
marcelamelara committed Feb 6, 2023
1 parent 52fa6cf commit 1a5c857
Show file tree
Hide file tree
Showing 2 changed files with 63 additions and 17 deletions.
27 changes: 12 additions & 15 deletions spec/v1.0-draft/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -86,10 +86,7 @@ in-toto in [ITE-5]. It is a [JSON] object with the following fields:
{
"_type": "https://in-toto.io/Statement/v1.0",
"subject": [
{
"name": "<NAME>",
"digest": {"<ALGORITHM>": "<HEX_VALUE>"}
},
{ <Reference> },
...
],
"predicateType": "<URI>",
Expand All @@ -98,7 +95,8 @@ in-toto in [ITE-5]. It is a [JSON] object with the following fields:
```

Version:
1.0.0 (see [parsing rules])
[1.0.0](https://github.com/in-toto/attestation/blob/v1.0/spec/README.md) (see
[parsing rules])

The Statement is the middle layer of the attestation, binding it to a particular
subject and unambiguously identifying the types of the [predicate]. It is a
Expand All @@ -109,29 +107,27 @@ subject and unambiguously identifying the types of the [predicate]. It is a
> Identifier for the schema of the Statement. Always
> `https://in-toto.io/Statement/v1.0` for this version of the spec.
`subject` _array of objects, required_
`subject` _array of objects([Reference], required_

> Set of software artifacts that the attestation applies to. Each element
> represents a single software artifact.
>
> IMPORTANT: Subject artifacts are matched purely by digest, regardless of
> content type. If this matters to you, please comment on
> [GitHub Issue #28](https://github.com/in-toto/attestation/issues/28)
> IMPORTANT: Subject artifacts SHOULD be matched by digest or by uri,
> regardless of MIME type.
`subject[*].digest` _object ([DigestSet]), required_

> Collection of cryptographic digests for the contents of this artifact.
>
> Subject-specific requirements:
> Two DigestSets are considered matching if ANY of the fields match. The
> producer and consumer must agree on acceptable algorithms. If there are no
> overlapping algorithms, the subject is considered not matching.
`subject[*].name` _string, required_

> Identifier to distinguish this artifact from others within the `subject`.
>
> The semantics are up to the producer and consumer. Because consumers evaluate
> the name against a policy, the name SHOULD be stable between attestations. If
> Subject-specific requirements:
> The `name` SHOULD enable consumers to distinguish this artifact from
> others within the `subject`. Because consumers evaluate the name against a
> policy, the `name` SHOULD be stable between attestations. If
> the name is not meaningful, use "\_". For example, a [SLSA Provenance]
> attestation might use the name to specify output filename, expecting the
> consumer to only considers entries with a particular name. Alternatively, a
Expand Down Expand Up @@ -255,6 +251,7 @@ Output (to be fed into policy engine):
[JSON]: https://www.json.org
[Link]: predicates/link.md
[Predicate]: #predicate
[Reference]: field_types.md#Reference
[RFC 3339]: https://tools.ietf.org/html/rfc3339
[SLSA Attestation Model]: https://slsa.dev/attestation-model
[SLSA Provenance]: https://slsa.dev/provenance
Expand Down
53 changes: 51 additions & 2 deletions spec/v1.0-draft/field_types.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ _DigestSet (object)_

> Set of alternative cryptographic digests for a single software artifact,
> expressed as a JSON map from algorithm name to lowercase hex-encoded value.
> Usually there is just a single key/value pair, but multiple entires MAY be
> Usually there is just a single key/value pair, but multiple entries MAY be
> used for algorithm agility.
>
> It is RECOMMENDED to use at least `sha256` for compatibility between
Expand All @@ -17,7 +17,7 @@ _DigestSet (object)_
> `sha3_224`, `sha3_256`, `sha3_384`, `sha3_512`, `shake128`, `shake256`,
> `blake2b`, `blake2s`, `ripemd160`, `sm3`, `gost`, `sha1`, `md5`
>
> Standard cryptographic hash algorithms, for cases when when the method
> Standard cryptographic hash algorithms, for cases when the method
> of serialization is obvious or well known.
>
> - `goModuleH1`: The go module [directory Hash1][], omitting the "h1:"
Expand Down Expand Up @@ -46,6 +46,52 @@ _DigestSet (object)_
> - `{"sha256": "abcd"}` does not match `{"sha256": "fedb", "sha512": "abcd"}`
> - `{"somecoolhash": "abcd"}` uses a non-predefined algorithm
<a id="Reference"></a>
_Reference (object)_

> A size-efficient representation of any artifact, metadata or attestation,
> referenced by another in-toto attestation.
> This type is designed to be backwards-compatible with the in-toto
> attestation [Statement v0.1][] as well as the [SLSA ArtifactReference][].
>
> Schema:
>```
> {
> "name": "<NAME>",
> "digest": { "<ALGORITHM>": "<HEX VALUE>", ... },
> "uri": "<RESOURCE URI>",
> "downloadURI": "<RESOURCE URI>", // optional
> "mimeType": "<MIME TYPE>" // optional
> }
>```
>
> Fields:
> - `name` (_string, required_): Human-readable identifier to distinguish
> the referenced object locally. The semantics are up to the producer and
> consumer.
> - `digest` (_[DigestSet], cond. required_): The producer and
> consumer must agree on acceptable algorithms. This field MUST be
> specified if the `uri` field is not present.
> - `uri` (_[ResourceURI], cond. required_): URI for the referenced
> object. When possible, this SHOULD be a universal and stable
> identifier, such as a source location or [Package URL][]. This
> field MUST be specified if the `digest` field is not present.
> - `downloadURI` (_[ResourceURI], optional_): The location of the
> referenced object. To enable automated downloads by consumers, the
> downloadURI SHOULD be resolvable.
> - `mimeType` (_string, optional_): The [MIME Type][] (i.e., media type)
> of the referenced object.
>
> Example:
> ```
> {
> "name": "rebuilderd-attestation",
> "digest": { "sha256": "abcdabcde..." },
> "downloadURI": "http://example.com/rebuilderd-instance/gcc_9.3.0-1ubuntu2_amd64.att",
> "mimeType": "application/vnd.in-toto+json"
> }
> ```
<a id="ResourceURI"></a>
_ResourceURI (string)_
Expand Down Expand Up @@ -85,7 +131,10 @@ _Timestamp (string)_
> Example: `"1985-04-12T23:20:50.52Z"`.
[directory Hash1]: https://cs.opensource.google/go/x/mod/+/refs/tags/v0.5.0:sumdb/dirhash/hash.go
[MIME Type]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types
[Package URL]: https://github.com/package-url/purl-spec/
[RFC 3339]: https://tools.ietf.org/html/rfc3339
[RFC 3986]: https://tools.ietf.org/html/rfc3986
[SPDX Download Location]: https://spdx.github.io/spdx-spec/package-information/#77-package-download-location-field
[SLSA ArtifactReference]: https://github.com/slsa-framework/slsa/blob/main/docs/provenance/v1/index.md#artifactreference
[Statement v0.1]: https://github.com/in-toto/attestation/blob/v0.1.0/spec/README.md#statement

0 comments on commit 1a5c857

Please sign in to comment.