ITE |
9 |
Title |
Introducing new in-toto Attestation types |
Sponsor |
Aditya Sirish A Yelgundhalli (@adityasaky) |
Status |
Draft |
Type |
Process |
Created |
2022-03-02 |
With ITE-6, in-toto opened the door to custom attestation types rather than the single fixed scheme. Various attestation types have been proposed, with some specified formally, and this highlighted the necessity for a formal process to develop, document, and discuss attestation types. This document introduces such a process.
The in-toto Attestation Framework enables developers to create authenticated metadata about various software artifacts. A more detailed explanation of this framework is available in ITE-6 and the formal definition.
When discussing a new attestation type, what is really being defined is a new type of predicate. The developer(s) of this new predicate must create a formal document that specifies the predicate type, and discusses several other related aspects. The purpose and prerequisites for the new attestation type MUST be defined. The document should also include a model that describes how the various components of the predicate map to supply chain semantics, juxtaposed with detailed use cases. These use cases SHOULD include example metadata that clearly highlight how the proposed predicate addresses the shortcoming described by them. Including these aspects will aid readers and future adopters understand the why and how of a particular attestation type.
The specification’s front matter MUST unambiguously declare a unique predicate
type, a version, and a unique, shorter predicate name following the rules
defined by the attestation framework. The predicate type along with the version
maps to the predicateType field in the Statement layer of an in-toto
attestation.
The short predicate name is used as the name of any files related to the predicate specification (specification document, directories, protobuf definition). The name must not include version information and is expected to only be used as an unauthenticated hint in other contexts such as a media type to indicate the predicate stored in an attestation.
For example, the in-toto link predicate has the predicate type
https://in-toto.io/attestation/link/VERSION. Its short name is just
link. Consequently, the specification file must be named link.md while the
protobuf definition must be named link.proto. A media type for an attestation
file that contains a link predicate may also use link to indicate the
predicate, for example application/vnd.in-toto.link+dsse.
Further, the specification MUST include a detailed schema of the fields that make up the predicate. The schema must clearly define the types of every field, with ranges for values where applicable. Also, the specification MUST contain rules for parsing the fields, as well as make recommendations for handling edge cases, where parsing or handling of fields would deviate from the standard Link:https://github.com/in-toto/attestation/tree/v1.0/spec/v1.0#parsing-rules[parsing rules]. For example, it may be preferable in some cases to silently allow extra, undefined fields, while in other cases such metadata should be rejected.
Since this process is designed to promote use of new attestation types across ecosystems and organizations, it is important to actually communicate the proposal to the broader in-toto community. The developers of the new type are encouraged to use the next community meeting, the mailing list, as well as other communication channels like Slack and IRC where the in-toto community has a presence to discuss the new document. This is a necessary step to list the new attestation type in the in-toto library of community reviewed attestation types.
ITE-6 established the in-toto/attestation repository where the specification for attestations is defined. This repository is also used to maintain a library of community reviewed predicate types. A group of community members has been selected to curate and generally maintain this library of attestations. This library of attestations provides peer-reviewed definitions of predicate types. These types are not mandated or endorsed, however we encourage use and refinement of the predicates in the library. Consistent adoption of standardised predicates helps achieve the in-toto Attestation Framework’s goal of building an ecosystem around software artifact metadata.
The new attestation definition SHOULD include the following fields.
This section must discuss at a high level the reason for creating the new attestation type. Essentially, it describes the problems that can be solved using the new attestation.
This section must discuss at least one concrete use case that will be covered by this predicate and how the current predicate types (if any) do not solve this.
New attestation types may be very specific to a particular technology or specification, which must be detailed in the prerequisites section. The in-toto Attestation Framework is likely a necessary prerequisite for all attestation types, but it SHOULD be explicitly mentioned to err on the side of caution.
The in-toto Attestation Framework was designed with software supply chain specific metadata in mind. However, supply chains are vast and composed of many different components and phases. Therefore, it is important for the attestation type to declare at a high level the steps and functionaries (in the generic) it is relevant to.
The schema of the attestation type is the core part of the document. It defines the fields included in an instantiation of the attestation type, as well as rules to parse them.
Parsing rules are important to define explicitly to ensure implementations can handle example attestations correctly. For example, this section can discuss how the attestation types are versioned, how non-specified fields must be handled, and so on. Attestations definitions MUST use this section to define how the parsing rules differ from the framework’s general parsing rules.
This subsection defines the fields that make up the new attestation type. At this point, it is important to remember that introducing a new attestation type really means introducing a new Predicate type. As such, this subsection MUST only define the Predicate and not any fields external to it, such as the Statement.
The fields must be listed with their names, the type of information they can hold, whether they are required or not, and a textual description of their expected contents. If the legal values for a field are known, or belong in a range, this must be specified in the description.
A new attestation type MUST include one or more examples. It is recommended that this example corresponds to the Purpose defined at the start of the document.
The example included MUST be an entire in-toto attestation document, and not just the predicate type. This will allow adopters and implementers to work with examples more easily.
For attestation definitions, it is important to be able to clearly map the changes made to the schema of the attestation to its different versions. These changes and the steps to migrate from one to another must be detailed where appropriate. This section MAY be skipped for the initial version of an attestation type.
The ITE process was designed to communicate enhancements or extensions to the in-toto specification. With ITE-6, in-toto enables developers to create new attestation types that allow for greater granularity when defining various supply chain activities and processes. However, while ITE-6 allows for these new attestations, it does not specify a specific, community-oriented process for introducing them. Further, there is no "blessed" location where consumers can find new attestation types. With this ITE, we aim to create a formal process for defining new in-toto attestation types, as well as to ensure the in-toto community is engaged when a new attestation type is proposed.
While ITE-6 defines the broad structure of new attestation types, it does not discuss how developer(s) should create these new types. ITE-6 also doesn’t specify the process developer(s) must use. The lack of a process can lead to the creation of arbitrary attestation types that may or may not function as intended, as well as a significant amount of fragmentation and redundancy—developers may well recreate different versions of attestation types that already exist.
The process itself has no security implications. However, when defining new attestation types, care must be taken to ensure the attestation performs the tasks it is designed for. It is also vital to understand clearly the claims made in an attestation as a misunderstanding may lead to unseen gaps existing in the software supply chain. More specific security concerns also apply to the individual contexts an attestation type is a part of.
ITE-6 led to the creation of the in-toto attestations repository. Currently, this repository contains the specification for the framework as well as a library of some attestation types. In future, this library may move to a stand-alone repository.
When introducing a new attestation type, it is important to take into account how the attestation must be validated. Such proposals should include a section on testing the fields of attestations, as well as a description of how the attestations must be verified. Essentially, this would require the definition to describe at least at a high level the structure of policies for the new predicate.