In-toto 3.0.0 verifies signed layouts, link metadata, and thresholds across multi-stage builds. Command-first reference. Read now.
What an in-toto layout actually enforces
In-toto 3.0.0 treats a software build as a chain of named steps, not a single black-box job. A signed layout is the contract: it names each step, which principals may run it, which materials (inputs) and products (outputs) that step must produce, and how those artifacts flow into later steps. Verification succeeds only when every required step is present, signed by an authorized key or identity, and consistent with the layout’s material and product rules. If a step is missing, reordered without permission, or claims products that do not match what the next step consumed, verification fails before you ship.
Layouts are the policy surface. Link metadata is the evidence. Each step emits a link that records what was read, what was written, and who signed for that run. Thresholds on the layout raise the bar: a critical step may require more than one independent signature so a single compromised runner cannot alone approve the stage. Across multi-stage builds—fetch sources, compile, test, package, publish—the layout is the map; the links are the receipts.
Command-first mental model for day-to-day work
Operate in three phases: define policy, collect evidence, verify the graph. First, author or review a layout that matches how your pipeline really runs—same step names, same expected artifacts, same authorized keys. Second, ensure every stage that the layout names actually produces link metadata and stores it with the build outputs. Third, run verification against the layout plus the full set of links for that release, not a partial subset from one job.
Keep commands and paths stable so links stay comparable across runs. Prefer explicit material and product paths over “whatever the workspace contains.” When a step is intentionally optional, model it in the layout rather than skipping link generation ad hoc; silent gaps look identical to a compromised or incomplete chain. Treat the layout file and the verification invocation as release artifacts: version them with the pipeline definition so you can re-verify old builds with the same rules you used at ship time.
Thresholds and multi-stage builds
Thresholds matter most where trust concentrates: signing a release artifact, promoting to production, or accepting third-party inputs. A threshold of one is fine for low-risk internal compile steps if a single CI identity is already tightly controlled. Raise thresholds for steps that mint supply-chain trust—packaging, image build, or publishing—so multiple independent signers must agree. Split long pipelines into stages with clear handoffs: each stage’s products become the next stage’s materials, and verification checks that handoff end to end.
- Require links for every layout-named step before promote or publish.
- Align material and product names across stages so verification can follow the graph without guesswork.
- Store links next to the build outputs they describe, not only in ephemeral CI logs.
- Rotate keys and update the layout together; stale authorized keys weaken thresholds.
Common verification failures and how to fix them
Most failures are operational, not exotic crypto bugs. A step ran under a different identity than the layout allows; link metadata was never uploaded; materials lists omit files that later products depend on; or two links claim the same step with conflicting digests. Fix by reconciling the layout with the real pipeline: correct step names, authorized keys, and artifact paths, then re-run only the affected stages so new links match current products. Re-verify the full chain after partial re-runs—thresholds and multi-stage rules apply to the complete set of links for that release, not to a single job log.
Use this reference as a checklist, not a ceremony: signed layouts define who may do what; link metadata proves what ran; thresholds raise the cost of a single bad actor or broken runner. Keep those three aligned with how you actually build, and in-toto 3.0.0 verification becomes a reliable gate rather than a flaky afterthought.