The main goal of in-toto is to provide authentication, integrity and auditability guarantees for the supply chain that created a final product that a client will install.
To avoid ambiguity, we will refer to any files in the final product that in-toto does not use to verify supply chain integrity as “target files”. Target files are opaque to the framework. Whether target files are packages containing multiple files, single text files, or executable binaries is irrelevant to in-toto.
The portion of the in-toto layout describing target files is the information necessary to indicate which functionaries are trusted to modify or create such a file. Additional metadata, besides layout and link metadata, can be provided along with target files to verify other properties of the supply chain (e.g., was a code review policy applied?) when inspecting the final product.
The following are the high-level steps for using the framework, as seen from the viewpoint of an operating system’s package manager. This is an error-free case:
In the context of in-toto, a role is a set of duties and actions that an actor must perform.
In the description of the roles that follows, it is important to remember that the framework has been designed to allow a large amount of flexibility for many different use cases. Given that every project uses a very specific set of tools and practices, this is a necessary requirement for in-toto.
There are three roles in the framework:
In addition, there are third-party equivalents of the above roles, which are managed by the sublayout mechanism, described in section 2.1.3. We will elaborate on these roles in depth now.
As previously stated, the project owner sets the required steps to be performed in the supply chain. For each step, its requirements, and the specific public keys that can sign for evidence of the step are included to ensure compliance and accountability. In addition, the layout file will contain the definition of inspection steps to be carried out when verifying the final product.
Functionaries are intended to carry out steps within the supply chain, and to provide evidence of this by means of link metadata.
A functionary is uniquely identified by the public key that they will use to sign a piece of link metadata as evidence that a step within the supply chain was performed.
A functionary can allow a third-party define a step or series of steps of the supply chain a sublayout. In this case, a subset of the steps to be performed are defined by such a functionary, who adopts the role of a project owner for this sublayout.
Clients are users or automated tools who want to use the product.
The client will perform verification on the final product. This includes verifying the layout metadata, and that the link metadata provided matches the specified layout described in the metadata, and performing inspection steps to ensure that any additional metadata and target files meet the criteria specified by the layout for this inspection step.
A client will likely not interact with the in-toto framework directly, as it should be integrated into system installation tools, or package managers.
Sublayouts allow a functionary to further define steps within the supply chain. When a functionary defines a sublayout, instead of carrying out the next step, they will define the series of steps required as if they were a project owner for the steps in this sublayout. This is helpful if the project owner does not know the specifics of a step, but trusts a functionary to specify them later.
Sublayouts can also be used for third-party sections of the supply chain. For example, a package maintainer for a Linux distribution will likely trust all the steps in the version control system as a sublayout defined by upstream developers of each package.
A in-toto implementation contains three main components:
To exemplify how these roles interact, we will describe a simple scenario. We provide more specific scenarios in section 5.3, after we have presented a more thorough description of the framework.
Consider a project owner, Alice, and her two functionaries, Diana and Bob. Alice wants Diana to write a Python script (foo.py). Then, Alice wants Bob to package the script into a tarball (foo.tar.gz). This tarball will be sent to the client, Carl, as part of the final product. Carl’s target file is foo.tar.gz.
When providing the tarball to Carl, Alice will create a layout file that Carl will use to make sure of the following:
In order to do this, Carl will require four files in the final product: first, Alice’s layout, describing the requirements listed above. Then, a piece of link metadata that corresponds to Diana’s action of writing a script, and a piece of link metadata for Bob’s step of packaging the script. Finally, the target file (foo.tar.gz) must also be contained in the final product.
When Carl verifies the final product, his installer will perform the following checks:
If all of these verifications pass, then installation continues as usual.
Figure 1: The supply chain
pieces for this example
The final product is the bundle of link metadata, layout metadata and target files that will be used by the client’s system. Additional, project-specific metadata can be also bundled in the final product for verification during inspection steps.
An installer or package manager uses the framework to inspect the final product and verify its contents. Each project will have specific requirements to verify. For example, a project may want to impose a review policy on the VCS. Thus, it requires in-toto to validate additional accompanying link and layout metadata to verify the review policy was followed.
The final product must contain at least these three files:
More complex and robust supply chain layouts will contain more pieces of link metadata, as well as additional sublayout files. Additional metadata (e.g., a signed git commit log) can also be provided to be used during inspection phases.
The supply chain layout specifies each of the different steps and its requirements, as well as the public keys used by functionaries to sign the link metadata for steps within the chain.
The layout will also specify how each piece of link metadata will be verified, and how the chain steps are interconnected via their materials and products.
Link metadata is a statement that a step was carried out. Each piece of link metadata will be used by the framework to ensure that the contents of materials and products have not been altered in an unauthorized manner (e.g., while in transit), and, that any alterations have been done only by an intended functionary.
A step may be performed a single time but it may be a part of multiple supply chains. in-toto supports such scenarios by not directly associating link metadata with a specific layout. Multiple layouts, therefore, can use the same link metadata during their respective verifications.
Target files are the files clients will install and use in their systems. For example, a target file could be an installation disk image, which will be bundled with link metadata for each step performed to create the target file.
Additional metadata files can be shipped within the final product for verification. In this case, inspection steps that utilize this metadata can be declared to determine if this metadata is correct. These metadata files will be treated as regular target files by the framework.
For more detailed information, refer to the Document Formats.