How to use the command 'in-toto-record' (with examples)

In-toto provides a framework for software supply chain security by allowing users to specify and verify a sequence of steps necessary for production and delivery. The in-toto-record command plays a crucial role in generating evidence of operations executed within the software supply chain. It allows users to create signed link metadata files which offer verifiable records of these operations, thereby enhancing the transparency and trustworthiness of the supply chain processes.

Use case 1: in-toto-record start

Code:

in-toto-record start -n path/to/edit_file1 path/to/edit_file2 ... -k path/to/key_file -m .

Motivation:

The in-toto-record start command is particularly useful in scenarios where you need to establish a verifiable record that a particular action or set of actions has begun in the software supply chain. By initiating a record, you offer a cryptographic assurance that these actions started at a specific time and involved specific artifacts or materials. This is widely used when changes or configurations to software are to be tracked and transparently documented from start to finish, ensuring there is no tampering or error introduced during the process.

Explanation:

• start: This signifies that you are beginning the record for a specific supply chain step, akin to pressing ‘record’ on a tape recorder.
• -n path/to/edit_file1 path/to/edit_file2 ...: The -n option specifies which materials or files are involved in this supply chain step. Each edit_file represents a file to be initially tracked.
• -k path/to/key_file: The -k option is crucial as it specifies the path to the cryptographic key file used to sign the record. This key ensures the integrity and authenticity of the recorded action.
• -m .: The -m option is followed by . which denotes that all files in the current working directory are considered as part of the material that is in use. This makes it easier when you want to track every file in a particular project directory.

Example output:

Created preliminary metadata file for step "edit_file1", "edit_file2", ...

This output indicates that the preliminary metadata files have been successfully created, marking the start of those recording steps.

Use case 2: in-toto-record stop

Code:

in-toto-record stop -n path/to/edit_file1 path/to/edit_file2 ... -k path/to/key_file -p .

Motivation:

The in-toto-record stop command is motivated by the need to finalize the record of a specified action or series of actions within the software supply chain. It ensures that modifications to files listed in the start command are properly documented and sealed with a signature to guarantee authenticity. This secure conclusion of record-keeping is essential, as it mitigates risks by providing a cryptographic link of changes over time, and affirms that the process was executed as planned.

Explanation:

• stop: Signals the conclusion of the recording step, akin to pressing ‘stop’ on a recorder.
• -n path/to/edit_file1 path/to/edit_file2 ...: Here, similar to the start command, the -n option indicates which products (output files) to record the stopping action for, giving a definitive list of involved files.
• -k path/to/key_file: The -k option continues to use the specified cryptographic key file. It ensures the final record is signed and verifiably authentic.
• -p .: The -p option followed by . means that all resulting products in the current directory are tracked. This is handy when all generated files during a build, for example, need to be included in the final metadata.

Example output:

Finalized metadata file for step "edit_file1", "edit_file2", ...

This output confirms that the metadata files have been finalized successfully, marking the completion of those specified actions or changes.

Conclusion:

The in-toto-record command enhances software supply chain security by providing a robust method to generate signed, verifiable records of supply chain steps. Through the use of start and stop commands, you can ensure the integrity and transparency of actions taken during software development and deployment processes. This helps in maintaining a high level of trust and accountability, essential in today’s software-driven environments.