Announcing Notary v2 alpha 1

By Steve Lasker, Microsoft Azure | Tuesday, October 26, 2021

Notary v1, otherwise known as Docker Content Trust, was released at at a time when there was one primary registry: Docker Hub. A lot has changed since then, some design choices around Trust on First Use (TOFU), key management, and a lack of content promotion within and across registries have become limiting factors for Docker Content Trust and Notary v1.

At KubeCon EU 2019, container image signing was the main topic of interest for a small group in the community. By December 2019, a multi-cloud, multi-vendor meeting kicked off Notary v2, as it was clear the time had come to solve the container image signing problem. Since 2019, multiple prototypes have been built validating the intended experiences around the Notary v2 goals, including how The Update Framework metadata can be partitioned, supporting content promotion.

Today, we are happy to announce the alpha 1 release of the Notary v2 project is ready for your feedback.

Notary v2 enables signing of all artifacts (Container Images, Software Bill of Materials, Scan Results) stored in OCI Distribution based registries, with ORAS artifacts spec enhancements. A key tenet of Notary v2 is that it enables promotion of signed artifacts within and across registries, including air-gapped and private network environments.

Graphic demonstrating promotion of an artifact, including building, importing, and deploying it

In addition to signature promotion, Notary v2 focuses on ease of use, with minimal dependencies. While Notary v2 can integrate with other supply chain efforts, there are no additional services required to sign or validate an artifact. As artifacts get promoted, users/entities may add new signatures, attesting to the validity of the content for the target environment, enabling a secure supply chain workflow.

Through signing, users choose the artifacts they trust, from the entities they trust, decoupling location from identity.

The Notary v2 Alpha includes the following releases:

notation - CLI enabling test-cert creation, cert/key configuration, sign and verify capabilities.
notation-go-lib - a set of Go libraries that may be incorporated into other tools, providing sign, configuration and verify capabilities.
Notary v2 specs - providing the specifications, such as the signature specification

To get a sense for how users can use the notation cli, we’ll walk through a few quick examples.

Sign & Verify

Signing and verification with the notation cli is as simple as:

export IMAGE=localhost:5000/net-monitor:v1
notation cert generate-test --default "wabbit-networks.io"
notation sign $IMAGE
notation cert add --name "wabbit-networks.io" ~/.config/notation/certificate/wabbit-networks.io.crt
notation verify $IMAGE

Animated screencast showing an image being signed using the notation CLI

Add and Sign other Supply Chain Artifacts

Notary v2 supports signing any artifacts stored in a registry, including SBOMs and Scan Results. Using notation-go-lib, tooling may incorporate these capabilities directly into various artifact CLIs.

export PRIVATE_REGISTRY=localhost:5050
export PRIVATE_REPO=${PRIVATE_REGISTRY}/net-monitor
export PRIVATE_IMAGE=${PRIVATE_REPO}:v1

# Simulate an SBOM
echo '{"version": "0.0.0.0", "artifact": "'${IMAGE}'", "contents": "good"}' > sbom.json

# Push to the registry with the oras cli
oras push $REPO \
  --artifact-type sbom/example \
  --subject $IMAGE \
  sbom.json:application/json

# Capture the digest of the SBOM, to sign it
SBOM_DIGEST=$(oras discover -o json \
                --artifact-type sbom/example \
                $IMAGE | jq -r ".references[0].digest")

notation sign $REPO@$SBOM_DIGEST

# Generate scan results with snyk
docker scan --json $IMAGE > scan-results.json
cat scan-results.json | jq

# Push the scan results to the registry, referencing the image
oras push $REPO \
  --artifact-type application/vnd.org.snyk.results.v0 \
  --subject $IMAGE \
  scan-results.json:application/json

# Capture the digest of the scan result, to sign the scan results
SCAN_DIGEST=$(oras discover -o json \
                --artifact-type application/vnd.org.snyk.results.v0 \
                $IMAGE | jq -r ".references[0].digest")

notation sign $REPO@$SCAN_DIGEST

# Only 1 tag, representing the one artifact
curl $PRIVATE_REGISTRY/v2/net-monitor/tags/list | jq

# Discover the additional attributes
oras discover -o tree $PRIVATE_IMAGE

Animated screencast showing an SBOM and scan results being pushed using ORAS and signed using the notation CLI

Notation Alpha 1 Features

The Notation alpha 1 release supports the following Notary v2 goals:

Offline signature creation
Signatures attesting to authenticity and/or certification
Maintain the original artifact digest and collection of associated tags, supporting existing dev through deployment workflows
Multiple signatures per artifact, enabling the originating vendor signature, public registry certification and user/environment signatures
Signature persistance within an OCI distribution-spec based registry, with oras artifacts spec enhancements
Air-gapped environments, where the originating registry of content is not accessible
Artifact and signature copying within and across OCI distribution-spec based registries, with oras artifacts spec enhancements
Verification of signatures, through a configuration based policy

Future versions of Notation will include:

Certificate revocation
Verification through policy, enabling environment specific validations
OCI Distribution 1.0 support (registries that don’t yet support the oras artifacts spec enhancements)
TUF meta-data support, enabling compromise resilience, revocation of keys and artifacts, and timeliness guarantees

Getting Started

Here are some resources to help get started with Notation and Notary V2:

← Previous