Requirements: Artifact Signing

[SteveLasker]

OCI Artifact Signing - Requirements

As containers become the common unit of deployment, users want to know the images in their private registries and their deployments are the same images that were initially published.

The OCI TOB has adopted OCI Artifacts, generalizing container images as one of many types of artifacts that may be stored in a registry. Other artifact types currently include:

• Singularity
• Helm Charts
• Car firmware updates, deployed from OCI Artifact registries

The Need for a Generalized Signing Solution

This document serves as the requirements and constraints of a generalized signing solution. It focused on the scenarios and needs, and very specifically avoids any reference to other projects or implementations. As our working group forms a consensus on the requirements, the group will then transition to a spec. Existing verification & signing solutions can be compared against the requirements and spec to identify best fits.

Key Stake Holders & Contributors

As we identify the requirements and constraints, a number of key contributors will be asked to represent their requirements and constraints.

Please add companies, projects, products that you believe should be included.

• Registry Cloud Operators
  • Azure Container Registry (acr) - Steve Lasker [email protected] (@SteveLasker)
  • AWS Container Registry (ecr)
  • Docker Hub
  • Google Container Registry (gcr)
  • GitHub Package Registry (gpr)
  • Quay
  • IBM Cloud Container Registry (icr)
• Registry Vendors, Projects & Products
  • Docker Trusted Registry
  • Harbor
  • JFrog Artifactory
• Artifact Types
  • Container Images - OCI Org
  • Helm Charts
  • Singularity

Requirements

As we begin a new design, we must ask what defines success.

Generic Artifact Support

While Docker Content Trust focused on container images, registries have evolved to now support any type of artifact. An image is just one of many artifacts. As a result, OCI has adopted OCI Artifacts

As we consider a new signing solution, we look to support any artifact to be signed, including images, Helm charts, OPA bundles, Singularity High Performance Computing images, to new, yet unknown artifacts.

Artifact Movement

1. As part of normal workflows, users move artifacts from one repository to another**. The movement of the artifact from dev-->staging-->production must not invalidate the signature.
2. As part of normal workflows, users move artifacts from one registry to another. The movement of the artifact must not invalidate the signature.
3. Users acquire artifacts from public registries, representing products. As they copy the artifact to their private registry, the signature must be verifiable as that of the source.

Signature Movement

1. Users place network rules on their deployments. These network rules restrict connections to trusted endpoints within the users control. The signature must be verifiable without having to reach untrusted endpoints. A user must be able to move signature information to services the user runs, and subsequently trusts.

Registry Operator Differentiated Value

1. Registry operators must be able to leverage other systems within their product and service lines. Specifically, the spec must allow for:

   1. External key management - leveraging other services they may provide
   2. Blob storage - leveraging unique cloud provider storage solutions
   3. Integrated authentication and authorization - while the spec must account for auth flows, each cloud provider must be able to provide flows that incorporate 2FA and service accounts

Open Topics

The following accounts for the list of open topics that should be considered.

Parking Log / Backlog

This section accounts for any topics the working group deems deferred for current conversation.

[wking]

An important design constraint is whether additional sigs can be added without changing the root image digest (i.e. what the mutable tag points to). If bumping tags is ok, sigs can live in CAS. If tags cannot be bumped, tags must live outside of CAS.

[wking]

Previous discussion in opencontainers/image-spec#22, opencontainers/image-spec#176, and opencontainers/image-spec#400.

[jtoberon]

An important design constraint is whether additional sigs can be added without changing the root image digest (i.e. what the mutable tag points to). If bumping tags is ok, sigs can live in CAS. If tags cannot be bumped, tags must live outside of CAS.

@wking Can you add more details to your note? When you say "can live in CAS," do you just mean within the manifest like in schema 1?

[wking]

When you say "can live in CAS," do you just mean within the manifest like in schema 1?

Manifests get pulled by reference, and references can be names or digest, so they're content addressable, but also tag-addressable (presumably to make space for HTTP content-negotiation for compat with clients who don't understand new media types). But now we have indexes, which are kind of tiptoeing into in-CAS content negotiation. By "in CAS" I mean "is pushed as an opaque blob and retrieved by digest", like we currently use for layers. It would be nice to be able to push whatever types you want (including signature objects) into the CAS blob store, and then push an array of descriptors as the mutable tag. Clients would request the tag by name, and the server would select an entry based on content negotiation Accept headers vs. the media types in the tag's descriptors. Then signed content looks like a GET /<repo-name>/tag/<tag-name> with Accept: some-signature-type, possibly with fallbacks in Accept to index, manifest, etc. types if you can accept unsigned content (e.g. because you're going to follow-up and verify the resulting digest with Notary or some other non-CAS signature store).

[vbatts]

i think this issue can be closed. This is the point of the Notary v2 discussion, and to store the signatures themselves as referenced blobs in a registry. Whether or not Notary v2 fully delivers on that is not a blocker for this distribution-spec.

[SteveLasker]

Adding links to Notary v2 efforts, and closing this issue as it's being tracked separatley:

• Notary v2 Requirements
• Notary v2 Scenarios
• Notary v2, Prototype-1