Skip to content

Latest commit

 

History

History
35 lines (24 loc) · 3.96 KB

303-verification-workflows.md

File metadata and controls

35 lines (24 loc) · 3.96 KB
Raw
Error in user YAML: (<unknown>): mapping values are not allowed in this context at line 1 column 21
---
title: CNAB Security: Verification workflows
weight: 303
---

Verification workflows

This document is a prescriptive part of CNAB Security.

The keywords MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in RFC 2119. The use of these keywords in this document are statements about how a CNAB implementation may fulfill the CNAB Security specification only.

Verification workflows

This section describes the verification workflow that runtimes compliant with the CNAB Security Specifications MUST perform in order to verify the provenance and attestation of bundles. Regardless of the bundle format, the verification workflow is the same, with the signature of a thin bundle being the content digest of the bundle.json file, while the signature of a thick bundle being the content digest of the bundle archive.

End-users SHOULD see no difference in their experience, unless an attack is caught. In that case, the installation of the bundle in question MUST be denied, and users SHOULD see an error message indicating why the verification workflow failed.

In order to download and verify a bundle, a compliant runtime MUST take the following steps:

  1. Use the TUF workflow to download trusted metadata about the desired bundle (e.g., example.com/example-org/example-bundle:latest) from the metadata repository. A bundle runtime MUST use the rules outlined in TAP 4 to securely resolve bundles from different metadata repositories on different servers.
  2. Download the (thin or thick) bundle itself. This operation can follow the CNAB Registries Specification for thin bundles and pull the bundle from an OCI registry, or use other protocols of obtaining it.
  3. Compare the observed hashes of the downloaded bundle to the trusted hashes. If they are not equal, the runtime MUST discard the downloaded bundle, report the error, and stop execution. Otherwise, go to the next step.
  4. If there is associated in-toto metadata about the bundle, use the TUF workflow to download in-toto root layout, public keys for the root layout, and link metadata for the bundle, and go to the next step. Otherwise, halt, and return the verified bundle to the user.
  5. Call the in-toto runtime to verify and inspect the bundle using the downloaded root layout, public keys for the root layout, link metadata, and the bundle itself.
    1. The bundle runtime MAY run in-toto directly on the operating system, in a default container image provided by the bundle runtime, or in a custom container image provided by the user. In any case, note that the bundle runtime SHOULD ensure that in-toto inspections, which are arbitrary commands, run within bounded resources (e.g., space, time) so as not to to run into accidental denial-of-service attacks. It is also up to the bundle developers to ensure that in-toto inspections are as portable as possible.
    2. If the verification and inspection of the bundle fails for any reason, the runtime MUST discard the downloaded bundle, report the error, and stop execution. Otherwise, if it passes, it MUST return the verified bundle to the user.

Note that in-toto security guarantees depend on the public keys for the root layout being signed with offline keys in the TUF targets metadata.