ITE |
6 |
Title |
Enabling contextual in-toto attestations |
Sponsor |
|
Status |
Accepted |
Type |
Standards |
Created |
2020-10-30 |
This in-toto enhancement (ITE) introduces the in-toto Attestation Framework, a specification for generating and expressing verifiable claims about software supply chains. An attestation is authenticated metadata about software artifacts and the processes that generate them. The framework allows users to define custom "predicates" with arbitrary, context-specific schemas. Several predicate types covering common cases have already been introduced, and accompanying ITEs have been proposed to define processes for creating predicate types and with new in-toto layout schemas that can verify them.
|
ℹ️
|
The in-toto Attestation Framework is defined in a stand-alone specification. This ITE presents a high level overview of the specification, and readers should refer to the latest versions of the full specification for all details. |
An attestation is a piece of authenticated metadata that expresses one or more claims about software artifacts and the supply chain producing them. This means that, as with traditional in-toto layout and link metadata, attestations are cryptographically signed and embedded in a signature envelope, such as DSSE.
All attestations have the following general schema:
{
"_type": "https://in-toto.io/Statement/<VERSION>",
"subject": [
{
"name": "<NAME>",
"digest": {"<ALGORITHM>": "<VALUE>"}
},
...
],
"predicateType": "<URI>",
"predicate": { ... }
}The _type field identifies the type of the object, which is unchanged from the
status quo. Old-style links use the value link. New-style attestations use the
value https://in-toto.io/Statement/<VERSION>;, where <VERSION> identifies the
major version of the schema. Implementations can support multiple versions
simultaneously using the _type field.
The predicate field contains the contextual metadata about the subject of
the attestation. Predicates are identified by the predicateType field, which
in-toto implementations must use to parse the contents of the predicate field.
Several predicate types have been proposed to cover common use cases such as SLSA Provenance for describing the origins of software artifacts, SPDX for supporting the SPDX SBOM standard, and link as a drop-in replacement for existing in-toto link metadata. This ITE is accompanied by other ITEs that describe how new predicate types can be introduced to the in-toto community, and update the in-toto layout schema to verify in-toto attestations.
The following in-toto attestation containing a link predicate:
{
"_type": "https://in-toto.io/Statement/v1",
"subject": [{"name": "out.bin", "digest": {"sha256": "fedc9876..."}}],
"predicateType": "https://in-toto.io/Link/v0.2",
"predicate": {
"name": "build",
"command": "make",
"materials": {"in.txt": {"sha256": "abcd1234..."}},
"byproducts": {},
"environment": {}
}
}is equivalent to the following old-style in-toto link:
{
"_type": "link",
"name": "build",
"command": "make",
"materials": {"in.txt": {"sha256": "abcd1234..."}},
"products": {"out.bin": {"sha256": "fedc9876..."}},
"byproducts": {},
"environment": {}
}This ITE was developed jointly by the in-toto maintainers, the Binary Authorization team, and what later became the SLSA team. The framework aligns with the SLSA Attestation Model and is officially recommended by SLSA.
The two main goals of this ITE are to:
-
Make it easier to author and consume arbitrary software artifact metadata. The existing link schema is rigidly focused on running a command that converts materials into products. Several types of metadata do not cleanly fit this model, such as:
-
Provenance of a CI/CD workflow, where there is no particular "command" to run.
-
Code review status.
-
Vulnerability scan result showing known vulnerabilities.
-
Policy decision allowing an artifact to be used in a particular environment.
-
-
Build a larger ecosystem around software artifact metadata that is not specific to in-toto (or Binary Authorization or any other consumer). By supporting a more generic, extensible attestation format, we allow CI/CD pipelines, vulnerability scanners, and other systems to generate a single set of attestations that can be consumed by anyone. Furthermore, this paves the way for in-toto to support existing formats, such as SPDX or CycloneDX.
The in-toto Attestation Framework specification provides more details and can be found here.
The new framework supports a drop-in replacement for in-toto link metadata, meaning that the types of claims supported up to this point can continue to be made. Link predicates will be supported as a drop-in replacement for old-style links in in-toto’s workflows.
Separately, in-toto implementations should continue to support old-style link metadata alongside attestations for a transitionary period of time. Implementers are free to determine the specific duration of this period, but it MUST be communicated to the in-toto community. For example, the in-toto reference implementation’s timeline of support for old-style links will be discussed in the official roadmap.
This ITE impacts the security of in-toto in a way that cannot be clearly defined here because security must be evaluated in the context of each individual predicate type. This is out of scope of this ITE and is delegated to each type.
Consider also that each additional predicate type supported adds complexity to implementations and thus adds some amount of residual risk due to the increased attack surface. Given that signatures are verified before predicate type parsing is performed, this risk increase should be from trusted parties who are acting malicious (e.g., insider attacks). Security weaknesses due to a predicate type are thus likely to result in a malicious functionary or sublayout creator being able to mask malicious behavior or escalate the trust in their role.
Note that the link predicate type is isomorphic to the existing link schema and can be translated freely in both directions.
As with security, each predicate type must be evaluated individually. To learn more, implementers are directed to ITE-9, which describes the process of introducing new predicate types and how they are evaluated.
in-toto’s Go implementation has served as the testbed for the Attestation Framework. Popular predicate types like SLSA Provenance have been implemented there and used in other applications.