Notary Project | A set of specifications and tools intended to provide a cross-industry standard for securing software supply chains. – Notary Project documentation

Docs: Authenticate with OCI-compliant registries

Mon, 01 Jan 0001 00:00:00 +0000

You can use notation to authenticate to an OCI-compliant registry. This is useful for inspecting artifacts in registries that do not offer a web frontend for view artifacts.

When you authenticate to an OCI-compliant registry, notation, by default, uses a credentials store to store your credentials in a secure manner. It is possible to store your credentials in environment variables or as base64 encoded values in a configuration file, but these approaches are not secure and are not recommended for production environments. It is strongly recommended that you use a credentials store to authenticate to an OCI-compliant registry.

Configure a credentials store

A credentials store is a secure location that stores your credentials, such as usernames and passwords. Operating systems often include a default credentials store, such as osxkeychain on macOS or wincred on Windows. You can also use a third-party credentials store, such as pass.

By default, notation uses a credentials store during the following operations:

Store credentials when you log in to a registry
Read credentials when accessing a registry to sign, verify, or display artifacts
Delete credentials from the credentials store when you log out of a registry

You have three options for configuring a credentials store:

Use the notation config.json file.
Use the Docker configuration file, which is located at ~/.docker/config.json.
Use the default credentials store for your operating system.

notation will resolve the credentials store in the order shown above. If no credential store is available and no other method is used for credentials, such as environment variables, notation login will not store the credentials and the command will fail.

Important

If you have Docker installed on your system and used docker login to authenticate to your OCI-compliant registry, your credentials are already stored and available to notation. In this case, you don’t need to run notation login again to authenticate to your OCI-compliant registry.

Docker also implements a fallback mechanism for storing your credentials. If no credentials store is available, Docker will store your credentials as base64 encoded values in the Docker configuration file. This is not secure and is not recommended for production environments. For more details, see docker login default behavior.

To configure a credentials store in the notation configuration file, add a credStore to the notation config.json file. The following example shows osxkeychain as the configured credentials store.

{
...
"credStore": "osxkeychain"
...
}

To configure a credentials store in the Docker configuration file, add a credStore to ~/.docker/config.json. The following example shows pass as the configured credentials store.

{
...
"credsStore": "pass"
...
}

Configure environment variables to authenticate to an OCI-compliant registry

Warning

Environment variables are not secure for storing sensitive data such as usernames and passwords and should not be used in a production environment.

Set the NOTATION_USERNAME and NOTATION_PASSWORD environment variables to authenticate to an OCI-compliant registry.

export NOTATION_USERNAME="YOUR_REGISTRY_USERNAME"
export NOTATION_PASSWORD="YOUR_REGISTRY_PASSWORD"

After the environment variables are set, you can use Notation with your registry without notation login.

For security reasons, unset the environment variables after you are done interacting with the OCI-compliant registry. For example:

unset NOTATION_USERNAME
unset NOTATION_PASSWORD

Configure `config.json` to authenticate to an OCI-compliant registry

Warning

Storing credentials in config.json is not secure for storing sensitive data such as usernames and passwords and should not be used in a production environment.

You can configure the notation config.json file to store the credentials for your OCI-compliant registry as base64 encoded values. For example:

{
"auths": {
"<registry>": {
"auth": "<base64encoded>",
}
},
}

Use `notation login` to authenticate to an OCI-compliant registry

To authenticate to an OCI-compliant registry, use the notation login command with your registry, username, and password. For example:

notation login -u <username> -p <password> <registry>

Note

If notation login is failing, you may need to Configure a credentials store. Alternatively in development and testing environments, you can use environment variables to authenticate to an OCI-compliant registry.

Use `notation logout` to log out of an OCI-compliant registry

To log out of an OCI-compliant registry, use the notation logout command with your registry. For example:

Warning

Using notation logout will remove the credentials from the configured credentials store. If you are using the Docker configuration file as your credentials store, notation logout will remove the credentials from the Docker configuration file.

If both the Docker configuration file and the notation configuration file are configured with a credentials store, notation logout will remove the credentials from credentials stored configured in the notation configuration file.

notation logout <registry>

OCI-compliant registries

For a full list of OCI-compliant registries compatible with notation, see OCI-compliant registries.

Docs: Create a trust policy and verify artifacts

Mon, 01 Jan 0001 00:00:00 +0000

As part of the process to verify a container image with Notation, you need to configure the trust policy to specify trusted identities that sign the artifacts, and the level of signature verification to use. For more details, see trust policy spec.

This tutorial shows you how to create a trust policy with different trusted identities and levels of signature verification.

Create an example registry with an image

Warning

The following example creates a registry with oras-project/registry. This registry should only be used for development purposes. When using other registries, ensure the registry is compatible with OCI Image specification v1.1.0. Starting with v1.0.0-rc.1 of notation, by default, signatures are stored using OCI Artifact Manifest, which is defined in OCI Image spec v1.1.0).

docker run -d -p 5000:5000 ghcr.io/oras-project/registry:v1.0.0-rc.3

Note

For Apple silicon, add the --platform linux/arm64 parameter.

Use docker buildx build and docker push to build and push a sample image to your registry.

docker buildx build -t localhost:5000/net-monitor:v1 https://github.com/wabbit-networks/net-monitor.git#main
docker push localhost:5000/net-monitor:v1

Save the digest value of the image from the output of docker push. For example:

The push refers to repository [localhost:5000/net-monitor]
2556c54bfdf3: Pushed
fb6ca4f9c8d3: Pushed
ded7a220bb05: Pushed
v1: digest: sha256:1111111111111111111111111111111111111111111111111111111111111111 size: 942

In the above example, the digest value of the image is sha256:1111111111111111111111111111111111111111111111111111111111111111.

Create example certificates and sign the image

Use notation cert generate-test to generate three example certificates and trust stores for signing the image.

notation cert generate-test valid-example
notation cert generate-test expired-example
notation cert generate-test missing-example

The valid-example certificate and trust store will be used to sign the image with a valid signature.
The expired-example certificate and trust store will be used to sign the image with an expired signature.
The missing-example certificate and trust store will not be used to sign the image, but will be used to demonstrate the trust policy.

Use notation ls to list the current signatures for your image. The following example sets the value of $IMAGE to the name of the image and its digest value.

Warning

Always use the digest value of an image when signing since they are immutable. Tag values are mutable and can reference a different container image than the original signed container image.

IMAGE=localhost:5000/net-monitor@sha256:1111111111111111111111111111111111111111111111111111111111111111
notation ls $IMAGE

Confirm there are no signatures listed.

Use notation sign to sign the image with two different signatures.

notation sign $IMAGE -k valid-example
notation sign $IMAGE --expiry 30s -k expired-example

Use notation ls to confirm there are two signatures.

notation ls $IMAGE
localhost:5000/net-monitor@sha256:1111111111111111111111111111111111111111111111111111111111111111
└── application/vnd.cncf.notary.v2.signature
├── sha256:2222222222222222222222222222222222222222222222222222222222222222
├── sha256:3333333333333333333333333333333333333333333333333333333333333333

Create a trust policy

Create a trustpolicy.json with the following trust policy in the notation configuration directory.

Note

For Linux, the notation configuration directory is ${HOME}/.config/notation/. For macOS, the notation configuration directory is ${HOME}/Library/Application\ Support/notation/. For Windows, the notation configuration folder is %USERPROFILE%\AppData\Roaming\notation\.

{
"version": "1.0",
"trustPolicies": [
{
"name": "trust-policy-example",
"registryScopes": [ "*" ],
"signatureVerification": {
"level" : "strict"
},
"trustStores": [ "ca:valid-example" ],
"trustedIdentities": [
"*"
]
}
]
}

The above example has a verification level of strict and uses the valid-example trust store.

Verify image signatures using the trust policy

The trust policy you created in the previous step uses a verification level of strict but there’s also permissive, audit, and skip. For more details on see trust policy spec.

Use notation verify to verify the image using the strict verification level and valid-example trust store and confirm it succeeds.

$ notation verify $IMAGE
Successfully verified signature for localhost:5000/net-monitor@sha256:1111111111111111111111111111111111111111111111111111111111111111

Update the trust store to use the expired-example trust store.

{
"version": "1.0",
"trustPolicies": [
{
"name": "trust-policy-example",
"registryScopes": [ "*" ],
"signatureVerification": {
"level" : "strict"
},
"trustStores": [ "ca:expired-example" ],
"trustedIdentities": [
"*"
]
}
]
}

Use notation verify to verify the image using the strict verification level and expired-example trust store and confirm it fails.

$ notation verify $IMAGE
Error: signature verification failed for all the signatures associated with localhost:5000/net-monitor@sha256:1111111111111111111111111111111111111111111111111111111111111111

This example fails because the strict verification level does not allow expired certificates. When creating the expired-example certificate and trust store, the certificate’s expiration was set for 30 seconds.

Update the trust policy to use the permissive verification level, which only logs if there is an expired certificate.

{
"version": "1.0",
"trustPolicies": [
{
"name": "trust-policy-example",
"registryScopes": [ "*" ],
"signatureVerification": {
"level" : "permissive"
},
"trustStores": [ "ca:expired-example" ],
"trustedIdentities": [
"*"
]
}
]
}

Use notation verify to verify the image using the permissive verification level and expired-example trust store and confirm it succeeds while logging the expired certificate.

$ notation verify $IMAGE
Warning: expiry was set to "logged" and failed with error: digital signature has expired on "Fri, 09 Dec 2022 16:30:07 -0600"
Successfully verified signature for localhost:5000/net-monitor@sha256:1111111111111111111111111111111111111111111111111111111111111111

Update the trust policy to use the missing-example trust store.

{
"version": "1.0",
"trustPolicies": [
{
"name": "trust-policy-example",
"registryScopes": [ "*" ],
"signatureVerification": {
"level" : "permissive"
},
"trustStores": [ "ca:missing-example" ],
"trustedIdentities": [
"*"
]
}
]
}

Use notation verify to verify the image using the permissive verification level and missing-example trust store and confirm it fails.

$ notation verify $IMAGE
Error: signature verification failed for all the signatures associated with localhost:5000/net-monitor@sha256:1111111111111111111111111111111111111111111111111111111111111111

This example fails because the permissive verification level does not allow missing certificates. When creating the missing-example certificate and trust store, the certificate was not used to sign the image.

Update the trust store to use the audit verification level.

{
"version": "1.0",
"trustPolicies": [
{
"name": "trust-policy-example",
"registryScopes": [ "*" ],
"signatureVerification": {
"level" : "audit"
},
"trustStores": [ "ca:missing-example" ],
"trustedIdentities": [
"*"
]
}
]
}

Use notation verify to verify the image using the audit verification level and missing-example trust store and confirm it succeeds while logging the missing certificate.

$ notation verify $IMAGE
Warning: authenticity was set to "logged" and failed with error: signature is not produced by a trusted signer
Successfully verified signature for localhost:5000/net-monitor@sha256:1111111111111111111111111111111111111111111111111111111111111111

Cleanup

Remove the notation configuration

To remove local keys, self-signed certificates, and notation configurations, remove the notation configuration directory.

For linux:

rm -r ${HOME}/.config/notation/

For macOS:

rm -r ${HOME}/Library/Application\ Support/notation/

For Windows, delete the directory %USERPROFILE%\AppData\Roaming\notation\

Remove the registry

To remove the registry running on your development computer:

docker rm -f $(docker ps -q)

Docs: Install the notation CLI

Mon, 01 Jan 0001 00:00:00 +0000

Warning

notation v2.0.0-alpha.1 is for testing purposes and not stable yet. The features in this release are subject to change until it reaches stable release v2.0.0.

Download and install the CLI for Linux

Download the latest stable release of the notation CLI binary for Linux and checksum file, then verify the integrity of the download.

Set the NOTATION_VERSION environment variable to the version of notation you want to download. The latest version is 2.0.0-alpha.1.

export NOTATION_VERSION=2.0.0-alpha.1

For ARM processors:

curl -LO https://github.com/notaryproject/notation/releases/download/v$NOTATION_VERSION/notation_$NOTATION_VERSION\_linux_arm64.tar.gz
curl -LO https://github.com/notaryproject/notation/releases/download/v$NOTATION_VERSION/notation_$NOTATION_VERSION\_checksums.txt
shasum --check notation_$NOTATION_VERSION\_checksums.txt

For x86 processors:

curl -LO https://github.com/notaryproject/notation/releases/download/v$NOTATION_VERSION/notation_$NOTATION_VERSION\_linux_amd64.tar.gz
curl -LO https://github.com/notaryproject/notation/releases/download/v$NOTATION_VERSION/notation_$NOTATION_VERSION\_checksums.txt
shasum --check notation_$NOTATION_VERSION\_checksums.txt

Confirm the shasum command succeeds for the archive file you downloaded. For example, the following shows a successful checksum verification for the notation_2.0.0-alpha.1_linux_arm64.tar.gz archive file:

...
shasum: notation_2.0.0-alpha.1_windows_amd64.zip: No such file or directory
notation_2.0.0-alpha.1_windows_amd64.zip: FAILED open or read
shasum: notation_2.0.0-alpha.1_linux_amd64.tar.gz: No such file or directory
notation_2.0.0-alpha.1_linux_amd64.tar.gz: FAILED open or read
notation_2.0.0-alpha.1_linux_arm64.tar.gz: OK
shasum: notation_2.0.0-alpha.1_darwin_amd64.tar.gz: No such file or directory
notation_2.0.0-alpha.1_darwin_amd64.tar.gz: FAILED open or read
shasum: notation_2.0.0-alpha.1_darwin_arm64.tar.gz: No such file or directory
notation_2.0.0-alpha.1_darwin_arm64.tar.gz: FAILED open or read
shasum: WARNING: 4 listed files could not be read
...

Expand the archive file directly into /usr/bin/:

tar xvzf <ARCHIVE_FILE> -C /usr/bin/ notation

Alternatively, you can expand the archive file to a different directory and add it to your path. For example, the following command expands the archive file to <EXAMPLE_PATH>/notation-cli/ and adds it to your path using the PATH variable in ~/.bashrc.

tar xvzf <ARCHIVE_FILE> -C <EXAMPLE_PATH>/notation-cli/ notation
echo 'export PATH="$PATH:<EXAMPLE_PATH>/notation-cli/"' >> ~/.bashrc

Download and install the CLI for macOS

Download the latest stable release of the notation CLI binary for macOS and checksum file, then verify the integrity of the download.

Set the NOTATION_VERSION environment variable to the version of notation you want to download. The latest version is 2.0.0-alpha.1.

export NOTATION_VERSION=2.0.0-alpha.1

For Apple Silicon processors:

curl -LO https://github.com/notaryproject/notation/releases/download/v$NOTATION_VERSION/notation_$NOTATION_VERSION\_darwin_arm64.tar.gz
curl -LO https://github.com/notaryproject/notation/releases/download/v$NOTATION_VERSION/notation_$NOTATION_VERSION\_checksums.txt
shasum --check notation_$NOTATION_VERSION\_checksums.txt

For Intel processors:

curl -LO https://github.com/notaryproject/notation/releases/download/v$NOTATION_VERSION/notation_$NOTATION_VERSION\_darwin_amd64.tar.gz
curl -LO https://github.com/notaryproject/notation/releases/download/v$NOTATION_VERSION/notation_$NOTATION_VERSION\_checksums.txt
shasum --check notation_$NOTATION_VERSION\_checksums.txt

...
shasum: notation_2.0.0-alpha.1_windows_amd64.zip: No such file or directory
notation_2.0.0-alpha.1_windows_amd64.zip: FAILED open or read
shasum: notation_2.0.0-alpha.1_linux_amd64.tar.gz: No such file or directory
notation_2.0.0-alpha.1_linux_amd64.tar.gz: FAILED open or read
shasum: notation_2.0.0-alpha.1_linux_arm64.tar.gz: No such file or directory
notation_2.0.0-alpha.1_linux_arm64.tar.gz: FAILED open or read
notation_2.0.0-alpha.1_darwin_amd64.tar.gz: OK
shasum: notation_2.0.0-alpha.1_darwin_arm64.tar.gz: No such file or directory
notation_2.0.0-alpha.1_darwin_arm64.tar.gz: FAILED open or read
shasum: WARNING: 4 listed files could not be read
...

Expand the archive file directly into /usr/local/bin:

sudo tar xvzf <ARCHIVE_FILE> -C /usr/local/bin/ notation

tar xvzf <ARCHIVE_FILE> -C <EXAMPLE_PATH>/notation-cli/ notation
echo 'export PATH="$PATH:<EXAMPLE_PATH>/notation-cli/"' >> ~/.zshrc

Download and install the CLI for Windows

Download the latest stable release of the notation CLI binary for Windows and checksum file:

Use the Get-FileHash command in powershell to generate the hash of the archive file.

(Get-FileHash .\notation_2.0.0-alpha.1_windows_amd64.zip).Hash

Compare the results of the command with the value in the checksum file. The two values should match.

Expand the archive file and add notation.exe to %ProgramFiles%/notation/bin

Alternatively, you can expand the archive file to a different directory and add it to your path.

Additional configuration

Important

notation automatically creates the NOTATION_CONFIG directory if it does not exist.

For more on the NOTATION_CONFIG directory and configuring your environment with notation see:

Docs: Overview

Mon, 01 Jan 0001 00:00:00 +0000

Introduction

The Notary Project is a set of specifications and tools intended to provide a cross-industry standard for securing software supply chains by using authentic container images and other OCI artifacts. Notation Project specifications and tooling provides signing and verification workflows for OCI artifacts, signature portability across OCI compliant registries, and integration with 3rd party key management solutions through a plugin model. Notary Project is also the name of the GitHub organization that has multiple prominent subprojects like Notation, Notary Project specifications, and Notary. Very often we use the name Notary Project to refer to all the above as well as the community that drives the specifications and the implementations. To learn more about Notary Project terms, please refer to the FAQ.

Here is a list of repositories under the Notary Project organization

Repository	Description
.github	This repository contains the Notary Project governance and other common documents that are shared across all repositories under the Notary Project organization.
meeting-notes	This repository contains the archived meeting notes.
notary	This repository contains the source code for the server and the client of the initial TUF-based implementation circa 2016.
specifications	This repository contains the latest Notary Project requirements, scenarios, specifications, and security audits to overcome the challenges from the initial implementation of 2016.
notaryproject.dev	This repository contains the source code and content for the Notary Project website.
notation	This repository contains the source code for the convenient CLI implementation of the new Notary Project specifications.
notation-go	This repository contains the source code for the convenient Golang library implementation of the new Notary Project signing and verification flow.
notation-core-go	This repository contains the source code for the Golang library implementation of the Notary Project signature (hereafter “Notary Project signature”) specification and wrapping (COSE and JWS).
roadmap	This repository is intended for keeping track of development activities in the Notary Project. It may be retired in the future as feature request and milestones are moved to the appropriate repositories.
tuf	This repository is intended for prototyping the storage of TUF metadata in OCI-compliant registries. It is not under active development at the moment but there are plans to revive it in the future.

Project status

The Notary Project is in active development. The latest release announcements are published on the Notary Project blog. The Notary Project community uses the project board for project planning and status tracking. You can also use GitHub milestones to track the progress of each repository:

Security

The Notary Project has a continuous fuzz testing implemented for the following repositories: notary, notation-go, and notation-core-go.

In addition, the Notary Project has had several public security audits:

Jul 7, 2023 by ADA Logics security audit covering notation, notation-go, and notation-core-go repositories.
Mar 21, 2023 by ADA Logics fuzz testing audit covering notary, notation-go, and notation-core-go repositories.
August 7, 2018 by Cure53) covering TUF and the notary repository.
July 31, 2015 by NCC covering notary repository.

Community

You can reach the Notary Project community and developers via the following channels:

Join the Notary Project Slack channel for discussions and to ask questions.
Follow the @NotaryProject for news about the Notary Project.
Join the Notary Project community meetings to stay on top of the latest discussions and development activities.
- Active meeting notes are captured at the Notary Project meeting notes
- Archived meeting notes are stored in the meeting-notes repository

Docs: Quickstart: Sign and validate a container image

Mon, 01 Jan 0001 00:00:00 +0000

Playground

You can also follow this guide on online remote cloud interactive playground on killercoda: https://killercoda.com/notaryproject/scenario/notation

Prerequisites

Before you begin, you need:

Docker installed and running, such as Docker desktop.
Notation CLI installed and configured.

Create an OCI-compatible registry

Create and run an OCI-compatible registry on your development computer using the distribution/distribution with the image deletion enabled. The following command creates a registry that is accessible at localhost:5001.

docker run -d -p 5001:5000 -e REGISTRY_STORAGE_DELETE_ENABLED=true --name registry registry

Note

If the host port 5001 is already in use, you can use another host port.

If you want to use Notation with other registries, refer to which registries support Notary Project signatures for more alternatives. See Authenticate with OCI-compliant registries when you log in to another OCI registry.

Add an image to the OCI-compatible registry

The following commands build and push the wabbit-networks/net-monitor container image to your container registry.

docker build -t localhost:5001/net-monitor:v1 https://github.com/wabbit-networks/net-monitor.git#main
docker push localhost:5001/net-monitor:v1

Get the digest value of the localhost:5001/net-monitor:v1 image using docker inspect. For example:

docker inspect --format='{{index .RepoDigests 0}}' localhost:5001/net-monitor:v1

Output:

sha256:073b75987e95b89f187a89809f08a32033972bb63cda279db8a9ca16b7ff555a

In the above example, the digest value is sha256:073b75987e95b89f187a89809f08a32033972bb63cda279db8a9ca16b7ff555a. The reference to the container image using the digest value is localhost:5000/net-monitor@sha256:073b75987e95b89f187a89809f08a32033972bb63cda279db8a9ca16b7ff555a.

Note

Notation resolves the tag to the digest before signing if a tag is used to identify the container image. Always reference and use the image digest instead of a tag since digest is immutable.

List the signatures associated with the container image

Use notation ls to show any signatures associated with the container image you built and pushed in the previous section.

IMAGE=localhost:5001/net-monitor@sha256:073b75987e95b89f187a89809f08a32033972bb63cda279db8a9ca16b7ff555a
notation ls $IMAGE

Confirm there are no signatures shown in the output.

Generate a test key and self-signed certificate

Use notation cert generate-test to generate a test RSA key for signing artifacts, and a self-signed X.509 test certificate for verifying artifacts.

Warning

A self-signed certificate should be used for testing or development purposes only.

The following command generates a test key and a self-signed X.509 certificate. With the --default flag, the test key is set as a default signing key. The self-signed X.509 certificate is added to a named trust store wabbit-networks.io of type ca.

notation cert generate-test --default "wabbit-networks.io"

Note

At this time, test key and self-signed certificate files created using notation cert generate-test can’t be removed using only notation key delete and notation cert delete. For more details on fully removing the test key and self-signed certificate files, see Remove the test key and self-signed certificate.

Use notation key ls to confirm the signing key is correctly configured. Key name with a * prefix is the default key.

notation key ls

Use notation cert ls to confirm the certificate is stored in the trust store.

notation cert ls

Sign the container image

Use notation sign to sign the container image.

notation sign $IMAGE

By default, the signature format is JWS. Use --signature-format to use COSE signature format.

notation sign --signature-format cose $IMAGE

The generated signature is pushed to the registry and the digest of the container image returned.

Use notation ls to show the signature associated with the container image.

notation ls $IMAGE

Confirm there is one signature, for example:

$ notation ls $IMAGE
localhost:5001/net-monitor@sha256:073b75987e95b89f187a89809f08a32033972bb63cda279db8a9ca16b7ff555a
└── application/vnd.cncf.notary.v2.signature
└── sha256:ba3a68a28648ba18c51a479145fca60d96b43dc96c6ab22f412c89ac56a9038b

Create a trust policy

To verify the container image, configure the trust policy to specify trusted identities that sign the artifacts, and level of signature verification to use. For more details, see trust policy spec.

Create a JSON file with the following trust policy, for example:

cat <<EOF > ./trustpolicy.json
{
 "version": "1.0",
 "trustPolicies": [
 {
 "name": "wabbit-networks-images",
 "registryScopes": [ "*" ],
 "signatureVerification": {
 "level" : "strict"
 },
 "trustStores": [ "ca:wabbit-networks.io" ],
 "trustedIdentities": [
 "*"
 ]
 }
 ]
}
EOF

Use notation policy import to import the trust policy configuration from a JSON file. For example:

notation policy import ./trustpolicy.json

Use notation policy show to view the applied policy configuration. For example:

notation policy show

The above JSON creates a trust policy named wabbit-networks-images. The policy has registryScopes set to *, which applies the policy to all the artifacts of any registry. The signatureVerification is set to strict, which checks all validations and any failure will fail the signature verification. This policy uses the wabbit-networks.io trust store of type ca which was created in the previous step. For more details on trust policies, see trust policy spec.

To enable trust policy for specific repositories, set the registryScopes to those specific repositories. For example:

"registryScopes": [
"localhost:5001/net-monitor",
"localhost:5001/nginx",
"localhost:5001/hello-world"
]

Verify the container image

Use notation verify to verify signatures associated with the container image.

notation verify $IMAGE

The digest of the supplied artifact is returned upon successful verification.

Cleanup

To remove the sample registry running on your development computer:

docker rm -f registry

To reset your notation configuration, remove the notation configuration directory. For more details, see Remove the configuration files.

Docs: Securely develop plugins for Notation

Mon, 01 Jan 0001 00:00:00 +0000

Important

Best practices for developing and distributing plugins for Notation are covered in the Notary Project specification for plugins. Carefully review that specification before developing and distributing plugins for Notation.

The following guidance is not a substitute for the Notary Project specification for plugins. It is intended to highlight key security considerations for developing and distributing plugins for Notation.

General security guidance

In general when developing your plugin, ensure you strictly adhere to the Notary Project specification for plugins.

Plugins run as a binary and are invoked by Notation. This means that the plugin has access to the same resources as the user running Notation. This includes access to the filesystem, network, and other resources. Ensure you are only accessing resources that are required for your plugin to function.

In some cases, your plugin may have access to sensitive data such as private keys. Ensure that you are not leaking this data to the filesystem, network, or other resources, including stdout and stderr.

If using the pluginConfig key/value store, do not store sensitive data in as the data is not encrypted and is stored as plaintext.

Securely distributing plugins

Ensure that you are distributing your plugin from a secure location and over a secure channel. For example, using a website or server you control and using HTTPS. If you are using a public repository, ensure it is a known, reputable repository that uses HTTPS, such as GitHub.

It is strongly recommended that you provide some way for users to verify the integrity of the plugin binary, such as providing a checksum or signature. This allows users to verify that the plugin binary has not been corrupted or tampered with.

Docs: Manage trust policies

Mon, 01 Jan 0001 00:00:00 +0000

By default, notation configures and manages a trust policy in the configuration directory. You can directly change the trust policy file in that directory to manage your trust policies.

Alternatively, you can manage trust policies using the notation policy import and notation policy show commands. These commands have the following benefits over directly editing the default trust policy file:

Significantly easier to manage multiple trust policies
You don’t need to know the name and location of the default trust policy file
Quickly view the current trust policy

To view the current trust policy, use notation policy show:

notation policy show

The following output shows an example of a trust policy:

$ notation policy show
{
"version": "1.0",
"trustPolicies": [
{
"name": "wabbit-networks-images",
"registryScopes": [ "*" ],
"signatureVerification": {
"level" : "strict"
},
"trustStores": [ "ca:wabbit-networks.io" ],
"trustedIdentities": [
"*"
]
}
]
}

You can override this trust policy by importing a new trust policy using notation policy import. For example, if you had the following trust policy defined in permissive-trustpolicy.json;

{
"version": "1.0",
"trustPolicies": [
{
"name": "wabbit-networks-images",
"registryScopes": [ "*" ],
"signatureVerification": {
"level" : "permissive"
},
"trustStores": [ "ca:wabbit-networks.io" ],
"trustedIdentities": [
"*"
]
}
]
}

The following command imports permissive-trustpolicy.json to override the trust policy:

notation policy import ./permissive-trustpolicy.json

The following example output shows notation importing the trust policy and prompting to confirm overwriting the existing trust policy:

$ notation policy import ./permissive-trustpolicy.json
Existing trust policy configuration found, do you want to overwrite it? [y/N] y
Trust policy configuration imported successfully.

Confirm the new trust policy by running notation policy show again. Notice that the signatureVerification level is now permissive:

$ notation policy show
{
"version": "1.0",
"trustPolicies": [
{
"name": "wabbit-networks-images",
"registryScopes": [ "*" ],
"signatureVerification": {
"level" : "permissive"
},
"trustStores": [ "ca:wabbit-networks.io" ],
"trustedIdentities": [
"*"
]
}
]
}

Docs: Quickstart: Sign and validate a non-image artifact

Mon, 01 Jan 0001 00:00:00 +0000

Prerequisites

Before you begin, you need:

Docker installed and running, such as Docker desktop.
Notation CLI installed and configured.

Create an OCI-compatible registry

docker run -d -p 5001:5000 -e REGISTRY_STORAGE_DELETE_ENABLED=true --name registry registry

Note

If the host port 5001 is already in use, you can use another host port.

If you want to use Notation with other registries, refer to which registries are compatible with the Notary Project for more alternatives. See Authenticate with OCI-compliant registries when you log in to another OCI registry.

Add an image to the OCI-compatible registry

The following commands build and push the wabbit-networks/net-monitor container image to your container registry.

docker build -t localhost:5001/net-monitor:v1 https://github.com/wabbit-networks/net-monitor.git#main
docker push localhost:5001/net-monitor:v1

Get the digest value of the localhost:5001/net-monitor:v1 image using docker inspect. For example:

docker inspect --format='{{index .RepoDigests 0}}' localhost:5001/net-monitor:v1

Output:

localhost:5001/net-monitor@sha256:073b75987e95b89f187a89809f08a32033972bb63cda279db8a9ca16b7ff555a

Note

Notation resolves the tag to the digest before signing if a tag is used to identify the container image. Always reference and use the image digest instead of a tag since digest is immutable.

Use an environment variable to store the digest value of the container image. This environment variable is used in later steps. For example:

IMAGE=localhost:5001/net-monitor@sha256:073b75987e95b89f187a89809f08a32033972bb63cda279db8a9ca16b7ff555a

Generate an SBOM for the container image

Use docker sbom to generate an SBOM for the container image. For example:

docker sbom --output SBOM.txt $IMAGE

Attach the SBOM to the container image

Use oras attach to attach the SBOM to the container image. For example:

oras attach $IMAGE SBOM.txt --artifact-type example/sbom

Use oras discover to confirm the SBOM is attached to the container image. For example:

oras discover $IMAGE -o tree

Confirm the SBOM is attached to the container image. For example:

localhost:5000/net-monitor@sha256:073b75987e95b89f187a89809f08a32033972bb63cda279db8a9ca16b7ff555a
└── example/sbom
└── sha256:6cbf7cc5ffa82b030b57ff820d49a86c143d8c6ac483b8e5eead81be8b223fc4

Use an environment variable to store the digest value of the SBOM. This environment variable is used in later steps. For example:

SBOM=localhost:5000/net-monitor@sha256:6cbf7cc5ffa82b030b57ff820d49a86c143d8c6ac483b8e5eead81be8b223fc4

List the signatures associated with the SBOM

Use notation ls to show any signatures associated with the SBOM you attached in the previous section.

notation ls $SBOM

Confirm there are no signatures shown in the output.

Generate a test key and self-signed certificate

Use notation cert generate-test to generate a test RSA key for signing artifacts, and a self-signed X.509 test certificate for verifying artifacts.

Warning

A self-signed certificate should be used for testing or development purposes only.

notation cert generate-test --default "wabbit-networks.io"

Note

Use notation key ls to confirm the signing key is correctly configured. Key name with a * prefix is the default key.

notation key ls

Use notation cert ls to confirm the certificate is stored in the trust store.

notation cert ls

Sign the SBOM

Use notation sign to sign the SBOM.

notation sign $SBOM

By default, the signature format is JWS. Use --signature-format to use COSE signature format.

notation sign --signature-format cose $SBOM

The generated signature is pushed to the registry and the digest of the SBOM is returned.

Use notation ls to show the signature associated with the SBOM.

notation ls $SBOM

Confirm there is one signature, for example:

$ notation ls $SBOM
localhost:5001/net-monitor@sha256:073b75987e95b89f187a89809f08a32033972bb63cda279db8a9ca16b7ff555a
└── application/vnd.cncf.notary.signature
└── sha256:ba3a68a28648ba18c51a479145fca60d96b43dc96c6ab22f412c89ac56a9038b

Create a trust policy

To verify the SBOM, configure the trust policy to specify trusted identities that sign the artifacts, and level of signature verification to use. For more details, see trust policy spec.

Create a JSON file with the following trust policy, for example:

cat <<EOF > ./trustpolicy.json
{
 "version": "1.0",
 "trustPolicies": [
 {
 "name": "wabbit-networks-images",
 "registryScopes": [ "*" ],
 "signatureVerification": {
 "level" : "strict"
 },
 "trustStores": [ "ca:wabbit-networks.io" ],
 "trustedIdentities": [
 "*"
 ]
 }
 ]
}
EOF

Use notation policy import to import the trust policy configuration from a JSON file. For example:

notation policy import ./trustpolicy.json

Use notation policy show to view the applied policy configuration. For example:

notation policy show

To enable trust policy for specific repositories, set the registryScopes to those specific repositories. For example:

"registryScopes": [
"localhost:5001/net-monitor",
"localhost:5001/nginx",
"localhost:5001/hello-world"
]

Verify the container image

Use notation verify to verify signatures associated with the SBOM.

notation verify $SBOM

The digest of the supplied artifact is returned upon successful verification.

Cleanup

To remove the sample registry running on your development computer:

docker rm -f registry

To reset your notation configuration, remove the notation configuration directory. For more details, see Remove the configuration files.

Docs: Sign and verify artifacts in CI/CD and GitOps

Mon, 01 Jan 0001 00:00:00 +0000

CI/CD

Notary Project provides solutions to help users sign and verify artifacts in CI/CD pipelines with Notation GitHub Actions and Azure DevOps. Follow the guidance below to get started Notation in CI/CD.

GitOps

In addition, Notary Project collaborates with the Flux community to enable signature verification in GitOps. The Flux source-controller supports verifying the authenticity of OCI artifacts signed with Notation. See Signatures verification with Notation in Flux for details.

Docs: Uninstall the notation CLI and its configuration

Mon, 01 Jan 0001 00:00:00 +0000

The notation CLI uses the following directories for its binaries and configuration files:

NOTATION_BIN is the directory for the notation binary.
NOTATION_LIBEXEC is the directory for other binaries, such as plugins, used by the notation.
NOTATION_CONFIG is the directory for the configuration files, including trust stores and trust policies.

Important

notation has default values for NOTATION_BIN, NOTATION_LIBEXEC, or NOTATION_CONFIG, but notation does not set those environment variables. These environment variables are optional, but if you wish to override the default values, you can set them to another value. For more details on each directory as well as the default location of those directories on each platform, see Notation directory structure for system configuration.

Remove the notation CLI

Delete the NOTATION_BIN directory to remove the notation binary.

Remove the additional binaries

Delete the NOTATION_LIBEXEC directory to remove the additional binaries, including plugins.

Remove the configuration files

Important

notation automatically creates the NOTATION_CONFIG directory if it does not exist. If you remove the NOTATION_CONFIG directory, notation will recreate the directory the next time you run a command.

Delete the NOTATION_CONFIG directory to remove the configuration files.

Remove the test key and self-signed certificate

You can generate a sample test key and self-signed certificate using notation cert generate-test. For example:

notation cert generate-test --default "wabbit-networks.io"

At this time, that key and self-signed certificate files can’t be removed using notation key delete and notation cert delete. To remove this key and self-signed certificate files, remove the key from the signing list and certificate from the trust store using notation key delete and notation cert delete, then manually delete the key and certificate files.

Use notation key ls to show the location of the key and certificate files. For example:

notation key ls
NAME KEY PATH CERTIFICATE PATH ID PLUGIN NAME
* wabbit-networks.io NOTATION_CONFIG/localkeys/wabbit-networks.io.key NOTATION_CONFIG/localkeys/wabbit-networks.io.crt

Use notation key delete to remove the key from the signing list. For example:

notation key delete wabbit-networks.io

Remove the key file using the path from notation key ls. For example:

rm NOTATION_CONFIG/localkeys/wabbit-networks.io.key

Use notation cert delete to remove the certificate reference from the trust store. For example:

notation cert delete --type ca --store wabbit-networks.io wabbit-networks.io.crt

Remove the certificate file using the path from notation key ls. For example to remove certificate file in BASH:

rm NOTATION_CONFIG/localkeys/wabbit-networks.io.crt

Docs: Customize the Notation configuration file

Mon, 01 Jan 0001 00:00:00 +0000

This guide demonstrates how to customize the Notation system configuration in config.json and signing key in signingkeys.json respectively. By default, you don’t need to create or modify them since Notation has default system settings and signing key configuration unless you want to customize them.

Location

The configuration file config.json location is different per operating system. signingkeys.json will be generated and stored in the same directory with config.json. You can use the Notation CLI or libraries to alter locations through the XDG_CONFIG_HOME environment variable.

Note

You can find the details of Notation directory structure for system configuration in this guide.

Linux

config.json should be manually created and placed in ~/.config/notation/config.json.

Windows

config.json should be manually created and placed in ~/AppData/Roaming/notation/config.json.

Darwin / macOS

config.json should be manually created and placed in ~/Library/Application Support/notation/config.json.

Sample of config.json

You can follow the example below to customize the Notation configuration in config.json

{
"credsStore": "pass",
"credHelpers": {
"registry.io": "pass"
},
"signatureFormat": "jws",
"insecureRegistries": [
"registry.wabbit-networks.io"
]
}

This table explains the properties in config.json.

Property	Type	Value
`credsStore`	string	default trust store name. Notation will read the configuration from Docker Credential Store by default unless you configure this filed in `config.json`
`credHelpers`	string	a registry host name address to trust store name map. Notation will read the configuration from Docker Credential Store by default unless you configure this filed in `config.json`
`signatureFormat`	string	define the signature envelope format, support jws or cose
`insecureRegistries`	array	a list of registries that may be used without https

Sample of signingkeys.json

Users only needs to interact with notation key command, which will generate/update this signingkeys.json file. An example of generated signingkeys.json is shown below.

{
"default": "wabbit-networks",
"keys": [
{
"name": "wabbit-networks",
"id": "some-remote-key-id",
"pluginName": "io.cncf.notary.v2.some.plugin"
},
{
"name": "import.acme-rockets",
"keyPath": "/home/demo/.config/notation/localkeys/import.acme-rockets.key",
"certPath": "/home/demo/.config/notation/localkeys/import.acme-rockets.crt"
}
]
}

This table explains the properties in signingkeys.json.

Property	Type	Value
`signingKeys.default`	string	signing key to be used when `notation sign` is called without `--name`
`signingKeys.keys`	array	collection of signing keys
`key.name`	string	named reference to a key
`key.id`	string	identifier of remote key
`key.pluginName`	string	name of plugin that should be used for signing
`key.keyPath`	string	location by which the key can be found by the notation cli or notation libraries
`key.certPath`	string	location by which the paired certificate can be found by the notation cli or notation libraries

Docs: Install and manage notation plugins

Mon, 01 Jan 0001 00:00:00 +0000

Plugins for notation provide functionality and integration with key stores and signing services. For example:

The notation-azure-kv plugin allows you to sign a Notation-generated payload with a private key in Azure Key Vault.
The AWS Signer plugin for Notation lets you sign and verify images using Notation with keys and certificates managed by AWS Signer, a signing service.
The Venafi CodeSign Protect plugin for Notation enables the secure signing and verification of images using the Venafi CodeSign Protect platform.

Install a plugin

To install a plugin, run the notation plugin install command to directly install a plugin either from a URL or from the host file system. This will create a {plugin-name} directory in {NOTATION_LIBEXEC}/plugins/ if the directory does not exist. The supported plugin file formats are .zip, .tar.gz and single plugin executable file. Alternatively, if you are using an application that bundles a plugin and the notation binary together, such as AWS Signer, see the installation instructions from the vendor.

Warning

Before creating the {plugin-name} directory, confirm you are using a name that follows the naming structure for plugins. Plugins that do not follow the naming structure will not be recognized by notation.

Usage

Install a plugin from file system:

notation plugin install --file <file_path>

Install a plugin from URL:

notation plugin install --sha256sum <digest> --url <HTTPS_URL>

plugin

The following examples show how to install each plugin on a Linux AMD64 machine. To install a plugin on other operating systems and architectures, please get the URL or plugin binary file from plugin vendors' website.

Install Notation AWS Signer plugin

To find out more about the AWS Signer plugin, please refer to their official documentation.

Install from file system

wget https://d2hvyiie56hcat.cloudfront.net/linux/amd64/plugin/latest/notation-aws-signer-plugin.zip
notation plugin install --file notation-aws-signer-plugin.zip
Successfully installed plugin com.amazonaws.signer.notation.plugin, version 1.0.298

Upon successful execution, the plugin is copied to Notation’s plugin directory.

Install Notation Azure Key Vault Plugin (v1.0.2)

To find out more about the Azure Key Vault Plugin, please refer to this GitHub repository.

Install from URL:

notation plugin install --url https://github.com/Azure/notation-azure-kv/releases/download/v1.0.2/notation-azure-kv_1.0.2_linux_amd64.tar.gz --sha256sum f2b2e131a435b6a9742c202237b9aceda81859e6d4bd6242c2568ba556cee20e
Downloading plugin from https://github.com/Azure/notation-azure-kv/releases/download/v1.0.2/notation-azure-kv_1.0.2_linux_amd64.tar.gz
Download completed
Successfully installed plugin azure-kv, version 1.0.2

Install from local file:

notation plugin install --file notation-azure-kv_1.0.2_linux_amd64.tar.gz
Successfully installed plugin azure-kv, version 1.0.2

Install Notation Venafi Plugin (v0.3.2)

To find out more about the Venafi Plugin, please refer to this GitHub repository.

Install from URL:

notation plugin install --url https://github.com/Venafi/notation-venafi-csp/releases/download/v0.3.2/notation-venafi-csp-linux-amd64.tar.gz --sha256sum f9e52bce64c8b6dcc9a7c8d5e204b911ba29a06fb8c35cefe9fd21cc5693a6d1
Successfully installed plugin venafi-csp, version 0.3.2-release

Install from local file:

notation plugin install --file notation-venafi-csp-linux-amd64.tar.gz
Successfully installed plugin venafi-csp, version 0.3.2-release

To confirm you plugin is installed, run notation plugin list. For example:

notation plugin list

Confirm the plugin is listed in the output. For example:

$ notation plugin list
NAME DESCRIPTION VERSION CAPABILITIES ERROR
azure-kv Sign artifacts with keys in Azure Key Vault 1.0.2 [SIGNATURE_GENERATOR.RAW] <nil>
com.amazonaws.signer.notation.plugin AWS Signer plugin for Notation 1.0.298 [SIGNATURE_GENERATOR.ENVELOPE SIGNATURE_VERIFIER.TRUSTED_IDENTITY SIGNATURE_VERIFIER.REVOCATION_CHECK] <nil>
venafi-csp Sign artifacts with keys in Venafi CodeSign Protect 0.3.2-release [SIGNATURE_GENERATOR.ENVELOPE SIGNATURE_VERIFIER.TRUSTED_IDENTITY] <nil>

Uninstall a plugin

To uninstall a plugin, use notation plugin uninstall.

notation plugin uninstall <plugin_name>

To confirm your plugin is uninstalled, run notation plugin list. For example:

notation plugin list

Plugin naming structure

The notation CLI strictly follows the Notary Project specification for plugins. This includes the naming structure for the plugin binary and the plugin directory. All plugins must be named notation-{plugin-name} and placed in the {NOTATION_LIBEXEC}/plugins/{plugin-name}/ directory. Also, you can’t modify the filename of the plugin binary from the tar.gz file when installing a plugin.

For example, the full path to the notation-azure-kv plugin is {NOTATION_LIBEXEC}/plugins/azure-kv/notation-azure-kv.

If the plugin name or plugin directory does not match the naming structure or the plugin name is altered, notation will not recognize the plugin.

Security best practices for plugins

Plugins are binaries that run on your host and can receive sensitive information from notation such as signatures, private keys, and payload data. As a result, it is strongly recommended that you follow these security best practices when using plugins:

Ensure that you only download plugins and their checksums from known, trusted sources
When available, use checksum verification or signature verification to confirm the plugin binary is not corrupted

Available plugins

The following plugins are currently available for notation:

AWS Signer plugin for Notation. For more details on using this plugin for sign and verify images, see Notation with AWS Signer
notation-azure-kv. For more details on using this plugin, see Sign a Notation-generated payload with a certificate in Azure Key Vault.
Venafi CodeSign Protect plugin for Notation that leverages the Venafi CodeSign Protect platform. For more details on using this plugin, see the usage instructions.

Docs: Manage images as OCI image layout

Mon, 01 Jan 0001 00:00:00 +0000

OCI image layout is a directory structure that contains files and folders that refer to an OCI image. OCI image layout is defined in OCI image spec. Using OCI image layout, you can sign images on local disk before pushing them to the remote registry.

Important

This feature is experimental. It is not recommended for production use.

Create OCI image layout for an image

Use docker buildx build with the --output type=oci flag to create an OCI image layout for an image.

For example, create a Dockerfile with the following content:

FROM alpine
CMD echo 'hello world!'

Use docker buildx create and docker buildx build to create an OCI image layout for the image defined in the Dockerfile.

docker buildx create --use
docker buildx build . -f Dockerfile -o type=oci,dest=hello-world.tar -t hello-world:v1

The above example sets output=hello-world.tar to save the OCI image layout as a tar file named hello-world.tar. To view the OCI image layout as a directory structure, extract the tar file.

mkdir hello-world
tar -xf ./hello-world.tar -C hello-world

Important

You must extract the tar file before you can sign an image as an OCI image layout.

Sign an image as an OCI image layout

To sign an existing image as an OCI image layout, enable the NOTATION_EXPERIMENTAL environment variable and use the notation sign command with the --oci-layout flag. The following example enables the NOTATION_EXPERIMENTAL environment variable, creates a self-signed certificate, and signs the image hello-world:v1 as an OCI image layout.

export NOTATION_EXPERIMENTAL=1
notation cert generate-test wabbit-networks.io --default
notation sign --oci-layout ./hello-world:v1

Note

Signatures are stored in the same OCI image layout directory, and associated with OCI image.

Use notation list --oci-layout to list signatures associated with an OCI image layout.

notation list --oci-layout ./hello-world:v1

Verify an image as an OCI image layout

You can verify an image as an OCI image layout using notation verify --scope and setting registryScopes in your trust policy. For example, the following trust policy has registryScopes set to local/hello-world:

{
"version": "1.0",
"trustPolicies": [
{
"name": "local-images-policy",
"registryScopes": [ "local/hello-world" ],
"signatureVerification": {
"level" : "strict"
},
"trustStores": [ "ca:wabbit-networks.io" ],
"trustedIdentities": [
"*"
]
}
]
}

The following command imports permissive-trustpolicy.json:

notation policy import ./permissive-trustpolicy.json

Use notation verify with --scope set to the same value you set in your trust policy to verify the image against signatures:

notation verify --oci-layout ./hello-world:v1 --scope "local/hello-world"

Push an OCI image layout to a remote registry

You can push an image to a remote registry as an OCI image layout on local disk using the oras CLI.

If you need a remote registry, you can create and run an OCI-compatible registry on your development computer using the distribution/distribution with the image deletion enabled. The following command creates a registry that is accessible at localhost:5001.

docker run -d -p 5001:5000 -e REGISTRY_STORAGE_DELETE_ENABLED=true --name registry registry

Use oras cp to push the OCI image layout to the remote registry. For example:

oras cp ./hello-world:v1 --from-oci-layout -r localhost:5001/hello-world:v1

Important

You must use the flag -r so that the signatures are copied together with the image.

Use notation list and notation verify to list and verify the image signatures. For example:

notation list localhost:5001/hello-world:v1
notation verify localhost:5001/hello-world:v1

OCI-compliant registries

For a full list of OCI-compliant registries compatible with notation, see OCI-compliant registries.

Docs: Securely deploying Notation

Mon, 01 Jan 0001 00:00:00 +0000

A deployment of Notation, specifically the notation CLI, is used for signing and verifying container images. The notation CLI is usually deployed on a development computer or in a CI/CD pipeline, such as GitHub Actions.

A deployment has several sensitive components:

It is strongly recommended that you follow the best practices in this document to secure your deployment of Notation. Notation works with a shared responsibility model, meaning users and organizations are responsible for securing the notation CLI deployment.

Failure to secure the filesystem on development computers and hosts with notation CLI deployments can result in malicious plugins being installed, trust policies being modified to allow verification compromised or untrusted artifacts, and trust stores being modified to have untrusted or compromised certificates.

Secure the installation and binary

When manually installing the binary, it is critical to download both the binary and its checksum from a trusted source, such as the notation GitHub repo, over HTTPS. You should also verify the checksum of the binary before using it. When using a package manager, such as Homebrew, it is critical to use a package manager that provides authenticity guarantees. For example, Homebrew uses GPG to verify the authenticity of the packages it installs.

When downloading the binary without installing it, for example to use it in a CI/CD pipeline, it is critical to download both the binary and checksum from a trusted source, such as the notation GitHub repo, over HTTPS. You should also verify the checksum of the binary. If all users on the host will need access to the binary, copy the binary to /usr/local/bin with the owner set to root and the permission set to rwxr-xr-x (755). This operation will require sudo or root access. If only one user, such as your account, will need access to the binary, copy the binary to a directory that users own with the owner set to that user and the permission set to rwx------ (700).

Secure the trust policy file

When creating a trust policy that only one user, such as your account, needs create the policy using notation policy import as that user without sudo. This approach ensures the policy file is stored in the correct directory with appropriate permissions.

Manually moving the trust file and setting the directory and file permissions is not recommended, but if you choose to do so, you must adhere to the following guidelines:

The policy file should be stored in a directory that user owns with the permission set to rwx------ (700).
The policy file should have the permission set to rw------- (600).

Secure certificates

When setting up a signing key for yourself, you should use your own account to do that. Never use sudo or as a separate user unless you are an admin and try to set up the signing key for that user. This recommendation applies for both the binary installed for all users on the system or just for you.

When downloading certificates for validation, always obtain them from trusted sources. For web-based downloads, using HTTPS. For vendor-specific sources, use the tools provided by the vendor. Use notation cert add to add the certificates to the trust store.

Manually moving certificates and setting the directory and file permissions is not recommended, but if you choose to do so, you must set the permissions for those certificate files to rw------- (600) to prevent access from other users since those certificates may contain confidential information.

Secure filesystem access

The sensitive components of a deployment of Notation are stored on the filesystem. For development computers managed by individuals and hosts directly managed by your organization, you should follow general best practices as well as your organization’s best practices for securing those development computers and hosts, such as:

Ensuring the operating system is fully patched
The disk encryption follows your organizations encryption policies
Use strong passwords and adhere to your organization’s password policies
Access to the Notation deployment directory is restricted to only authorized users, such as those with sudo access, administrators, or the user that owns the directory

Every organization has different policies and best practices for securing development computers and hosts, and they should be followed as a part securing filesystem on development computers and hosts with notation CLI deployments.

Other security best practices

For development computers managed by individuals and hosts directly managed by your organization, ensure the access to those systems as well as locations of the sensitive components of a deployment of Notation are restricted to only authorized users.

For computers not directly managed by individuals or your organization, such as hosts used for CI/CD pipelines, ensure manner in which the sensitive components of a deployment of Notation are stored, accessed, and transmitted to those computers follows your organizations best practices and are restricted only to authorized users.

Docs: Experimental features

Mon, 01 Jan 0001 00:00:00 +0000

Starting in version v1.0.0-rc.4, Notation began introducing experimental features. Experimental features are features that are not yet ready for production use but are available for testing and evaluation. Experimental features may change significantly in later releases or be completely removed. Experimental features are not enabled by default and are not supported.

Currently, Notation has the following experimental features:

Signing, listing and verifying images as OCI image layout
Store signatures using artifact manifest (requires registry support). Deprecated in v1.0.0-rc.5.
Use Referrers API

To enable experimental features, set the NOTATION_EXPERIMENTAL environment variable to 1, for example:

export NOTATION_EXPERIMENTAL=1

Docs: Manage signatures

Mon, 01 Jan 0001 00:00:00 +0000

Important

When managing signatures on artifacts in remote repositories that require authentication, you must authenticate using notation login before you can manage signatures on artifacts in those repositories. For more information, see Authenticate to a remote repository.

List signatures on an artifact

Use notation list to show the signatures associated with an artifact.

Important

When using notation list, use the fully qualified artifact reference, including the digest. For example, localhost:5001/net-monitor@sha256:111222333444555666777888999000aaabbbcccdddeeefff0001112223334445. You can use notation list with a tag, for example, localhost:5001/net-monitor:latest. Using a tag is not recommended since a tag is mutable and may be updated to point to a different version of the artifact. A digest is not mutable and always points to the same version of the artifact.

To find the digest of an artifact, use notation list with the artifact reference. For example, notation list localhost:5001/net-monitor:v1. You can also use oras manifest fetch --descriptor on OCI registries. For example, oras manifest fetch --descriptor REGISTRY/IMAGE:TAG.

IMAGE=localhost:5001/net-monitor@sha256:111222333444555666777888999000aaabbbcccdddeeefff0001112223334445
notation list $IMAGE

The following example shows an artifact with one signature:

$ notation list $IMAGE
localhost:5001/net-monitor@sha256:111222333444555666777888999000aaabbbcccdddeeefff0001112223334445
└── application/vnd.cncf.notary.v2.signature
└── sha256:ba3a68a28648ba18c51a479145fca60d96b43dc96c6ab22f412c89ac56a9038b

Inspect a signature on an artifact

Use notation inspect to inspect the signatures of an artifact. For example:

$ notation inspect $IMAGE
Inspecting all signatures for signed artifact
localhost:5001/net-monitor@sha256:111222333444555666777888999000aaabbbcccdddeeefff0001112223334445
└── application/vnd.cncf.notary.signature
├── sha256:1bf07b33089e65e9e83a780c7f405ba36aa4ef2b2fb031535cc6e89042ac0a0f
│ ├── media type: application/jose+json
│ ├── signature algorithm: RSASSA-PSS-SHA-256
│ ├── signed attributes
│ │ ├── signingScheme: notary.x509
│ │ └── signingTime: Sun Jun 11 19:56:47 2023
│ ├── user defined attributes
│ │ └── (empty)
│ ├── unsigned attributes
│ │ └── signingAgent: Notation/1.0.0
│ ├── certificates
│ │ └── SHA256 fingerprint: 3f32321edede5df5bb02e88749217ef10c6c4ce8a5d62bb2136257a0ade6e832
│ │ ├── issued to: CN=wabbit-networks.io,O=Notary,L=Seattle,ST=WA,C=US
│ │ ├── issued by: CN=wabbit-networks.io,O=Notary,L=Seattle,ST=WA,C=US
│ │ └── expiry: Mon Jun 12 18:56:09 2023
│ └── signed artifact
│ ├── media type: application/vnd.docker.distribution.manifest.v2+json
│ ├── digest: sha256:111222333444555666777888999000aaabbbcccdddeeefff0001112223334445
│ └── size: 942
└── sha256:e503cadaa2ffee0272acc8ec1dcb4f737a7245b01491e86b9a382ca3fed88297
├── media type: application/cose
├── signature algorithm: RSASSA-PSS-SHA-256
├── signed attributes
│ ├── signingScheme: notary.x509
│ └── signingTime: Sun Jun 11 19:57:14 2023
├── user defined attributes
│ └── (empty)
├── unsigned attributes
│ └── signingAgent: Notation/1.0.0
├── certificates
│ └── SHA256 fingerprint: 3f32321edede5df5bb02e88749217ef10c6c4ce8a5d62bb2136257a0ade6e832
│ ├── issued to: CN=wabbit-networks.io,O=Notary,L=Seattle,ST=WA,C=US
│ ├── issued by: CN=wabbit-networks.io,O=Notary,L=Seattle,ST=WA,C=US
│ └── expiry: Mon Jun 12 18:56:09 2023
└── signed artifact
├── media type: application/vnd.docker.distribution.manifest.v2+json
├── digest: sha256:111222333444555666777888999000aaabbbcccdddeeefff0001112223334445
└── size: 942

The output contains all the certificate information used for signing the artifact. You can use this information to validate the signing certificates and certificate chain.

The output also contains details about the artifact that was signed, such as the digest. You can use this information to confirm that the correct artifact was signed.

Delete a signature on an artifact

Use notation list to list signatures associated with an artifact. For example:

notation list $IMAGE
localhost:5001/net-monitor@sha256:111222333444555666777888999000aaabbbcccdddeeefff0001112223334445
└── application/vnd.cncf.notary.signature
└── sha256:fffeeedddcccbbbbaaa000999888777666555444333222111000fff000eee0000

In the above example, the digest of the signature is sha256:fffeeedddcccbbbbaaa000999888777666555444333222111000fff000eee0000.

Use the oras CLI to delete the signature with oras manifest delete. For example:

oras manifest delete --distribution-spec v1.1-referrers-tag localhost:5001/net-monitor@sha256:fffeeedddcccbbbbaaa000999888777666555444333222111000fff000eee0000
Are you sure you want to delete the manifest "sha256:fffeeedddcccbbbbaaa000999888777666555444333222111000fff000eee0000" and all tags associated with it? [y/N] y
Deleted localhost:5001/net-monitor@sha256:fffeeedddcccbbbbaaa000999888777666555444333222111000fff000eee0000

Confirm that the signature is deleted with notation list. For example:

notation list $IMAGE
localhost:5001/net-monitor@sha256:111222333444555666777888999000aaabbbcccdddeeefff0001112223334445 has no associated signature

The above example shows that the only signature associated with the artifact is deleted.

Docs: Notary Project specifications and requirements

Mon, 01 Jan 0001 00:00:00 +0000

More information on the Specifications, requirements, and other details about the Notary Project can be found in the Specification repository.

Docs: Frequently asked questions

Mon, 01 Jan 0001 00:00:00 +0000

JWS signature envelope

Q: Why is JWT not used as the signature envelope format?

A: JWT uses JWS compact serialization which do not support unsigned attributes. Notary Project signature requires support for unsigned attributes. Instead we use the JWS JSON Serialization representation, which supports unsigned attributes.

Q: Why JWT exp and iat claims are not used?

A: Unlike JWT which always contains a JSON payload, Notary Project OCI Signature Specification envelope can support payloads other than JSON, like binary. Reusing the JWT payload structure and claims, limits the signature envelope to only support JSON payload, which is not extendable. Also, reusing JWT claims requires following same claim semantics as defined in JWT specifications. The exp claim requires that verifier MUST reject the signature if current time equals or is greater than exp, where as the Notary Project’s trust store and trust policy allows verification policy to define how expiry is handled.

Signature specification

Q: How will Notation support multiple signature envelope formats?

A: The mediaType of artifact manifest’s blob identifies the signature envelope type.
The client implementation can use the aforementioned mediaType to parse the signature envelope.

Q: How will Notation support multiple payload formats?

A: The Signature envelope MUST have a versioning mechanism to support multiple payload formats. For JWS JSON serialization signature envelope, versioning is achieved by the cty field in ProtectedHeaders.

Signature scheme

Q: What is the relationship of Signing Scheme with Signature Envelope format?

A: Signing Scheme aims to be agnostic of the Signature Envelope format. A given signing scheme can be implemented through any signature envelope format (such as JWS or COSE) as long as it can support the required signature schema used by the signing scheme.

Q: Why is the trust store used for Signing Authority (x509/signingAuthority) distinct from trust store for Certificate Authority (x509/ca), why can’t they share the same trust store?

A: Signing Authority is a different type of trusted entity as compared to Certificate Authority (CA) or Timestamping Authority (TSA). A CA is trusted for verifying the identity of a signing entity (end user) and issuing it a certificate, whereas a TSA is trusted to generate authentic timestamp. In contrast, an SA is trusted to generate signatures on behalf of an end user (signature requestor) and also to generate authentic timestamp as part of the signature. If we use a shared trust store for CA and SA, a verifying entity does not have the ability to differentiate between CA and SA when the verifying entity configures trusted roots in the trust store. This has implication such as an end user with CA issued certificate can masquerade themselves as an SA by generating a signature with signing scheme notary.x509.signingAuthority.

Trust store and trust policy

Q: Does the trust policy of the Notary Project specification and its implementation in Notation support n out of m signatures verification requirement?

A: The Notary Project specifications and its implementation in Notation doesn’t support n out m signature requirement verification scheme. Signature verification workflow succeeds if verification succeeds for at least one signature.

Q: Does the Notary Project specification and its implementation in Notation support overriding of revocation endpoints to support signature verification in disconnected environments?

A: Not natively supported but a user can configure revocationValidations to skip and then use extended validations to check for revocation.

Q: Why user needs to include a complete certificate chain (leading to root) in the signature?

A: Without a complete certificate chain, the implementation won’t be able to perform an exhaustive revocation check, which will lead to security issues, and that’s the reason for enforcing a complete certificate chain.

Q: Why are we validating artifact signature first instead of signing identity?

A: Ideally, we should validate the signing identity first and then use the public key in the signing identity to validate the artifact signature. However, this will lead to poor performance in the case where the signature is not valid as there are lots of validations against the signing identity including network calls for revocations, and possibly we won’t even need to read the trust store/trust policy if the signature validation fails. Also, by validating artifact signature first we will still fail the validation if the signing identity is not trusted.

Notary Project Terms

Below are the frequently asked questions about Notary Project terms. For detailed definitions of each Notary Project term, please refer to the glossary page.

Q: What is Notary Project?

A: The Notary Project is a set of specifications and tools intended to provide a cross-industry standard for securing software supply chains by using authentic container images and other OCI artifacts. Notary Project is also the name of the GitHub organization that has multiple prominent subprojects like Notation, Notary Project specifications, and Notary. Very often we use the name Notary Project to refer to all the above as well as the community that drives the specifications and the implementations.

Q: How are Notary and Notary Project related?

A: Notary is one of the subprojects under the Notary Project organization. Notary uses The Update Framework (TUF) to implement client and server components that run and interact with trusted collections that describe the content in a container registry. The name Notary comes from the notary CLI that is used to manage the trusted collections. The code that has the implementation of the client and the server components is available in the notaryproject/notary repository.

Q: What is the difference between Notary Project and TUF?

A: The Update Framework (aka TUF) is a CNCF graduated project that helps developers maintain the security of software update systems. TUF is a separate community and separate GitHub organization. One of the subprojects under Notary Project, notary, uses TUF for the implementation.

Q: What is Notary Project specification?

A: Due to some portability challenges with the TUF-based implementation in Notary, circa 2019, the Notary Project community decided to work on a portable signature specification. This resulted in the creation of the specifications subproject. The Notary Project specifications are shared across repositories under Notary Project as well as used by other open-source projects and/or vendor tools that want to interoperate with the Notary Project tooling. The Notary Project community plans to add other specifications in the future as our work on software supply chain evolves.

Q: Does Notary Project signature specification leverage TUF?

A: No, the Notary Project signature specification does not leverage TUF.

Q: What is the difference between Notation and Notary?

A: Notation and Notary are both subprojects of Notary Project and offer capabilities for signing container images. Notation implements the new Notary Project signing specification and workflows while Notary is based on The Update Framework (TUF) and does not implement any of the Notary Project specifications. While Notation has a CLI and libraries and leverages existing key management infrastructure and OCI-compliant registries, Notary has a server and client components. An example of a notary implementation is Docker Content Trust (DCT). In addition to signing artifacts, Notation handles artifact verification, signature portability, and integration with third-party key/certificate management solutions via a plugin model.

Q: I’ve heard the term “Notary v2”. What does this mean?

A: The term “Notary v2” or “notary v2” was previously used by members of the Notary Project community and others. However, various meanings were ascribed to it, leading to its ambiguous usage with some people referring to it as the entire Notary Project and others as the Notation CLI. Because of this ambiguity, the term “Notary v2” or “notary v2” is no longer used by the Notary Project community. While the term may still be visible in some articles on the internet, the name “Notary v2” or “notary v2” is only preserved for historical reasons and will not be used by the Notary Project community going forward.

Docs: Notation directory structure for system configuration

Mon, 01 Jan 0001 00:00:00 +0000

Notation CLI requires local file systems support for the following components. They should be stored in different places per different operating system.

Notation binary
Plugins
Configurations
Trust stores
Trust policies
Signing key store
Caches

This documentation specifies the recommended directory structure for those components.

Alias	Description
`NOTATION_BIN`	Directory for executable binaries
`NOTATION_LIBEXEC`	Directory for binaries not meant to be executed directly by users' shell or scripts
`NOTATION_CONFIG`	Directory for configurations
`NOTATION_CACHE`	Directory for caches, such as Certificate Revocation List (CRL) caches

Directory	Unix	Windows	Darwin
`NOTATION_LIBEXEC`	`$XDG_CONFIG_HOME/notation`	`%AppData%/notation`	`~/Library/Application Support/notation`
`NOTATION_CONFIG`	`$XDG_CONFIG_HOME/notation`	`%AppData%/notation`	`~/Library/Application Support/notation`
`NOTATION_CACHE`	`$XDG_CACHE_HOME/notation`	`%LocalAppData%/notation`	`~/Library/Caches/notation`

Structure

The overall directory structure for notation is summarized as follows.

{NOTATION_BIN}
└── notation
{NOTATION_CACHE}
└── crl
└── {sha256-hash-of-the-CRL-downloading-URL}
{NOTATION_CONFIG}
├── config.json
├── localkeys
│   ├── {key-name}.crt
│   └── {key-name}.pem
├── signingkeys.json
├── trustpolicy.json
└── truststore
└── {trust-store-type}
└── {named-store}
└── {cert-file}
{NOTATION_LIBEXEC}
└── plugins
└── {plugin-name}
└── notation-{plugin-name}

Notation Binary

The path for the notation binary is as follows.

{NOTATION_BIN}/notation

On Windows, the .exe extension is required for executables.

{NOTATION_BIN}/notation.exe

Plugin

Plugins are binaries not meant to be executed directly by users' shell or scripts. The path of a plugin follows the pattern below.

{NOTATION_LIBEXEC}/plugins/{plugin-name}/notation-{plugin-name}

On Windows, the .exe extension is required for executables.

{NOTATION_LIBEXEC}/plugins/{plugin-name}/notation-{plugin-name}.exe

General Configuration

The path of the general configuration file of the notation CLI is as follows.

{NOTATION_CONFIG}/config.json

Trust Store

A trust store is a directory located within the filesystem that contains multiple collections of certificates, which are used to validate signatures. The Notary Project trust store currently support three types of certificates:

Certificates from Certificate Authorities (CAs), which are stored in the X509/ca directory.
Signing Authority certificates, stored in the X509/signingAuthority directory.
Time Stamping Authority (TSA) certificates, which will be supported in future releases and will be stored in the X509/tsa directory.

These sub-directories also known as named stores support certificate files with the .pem, .crt, and .cer extensions.

The path of a certificate file in a Trust Store follows the pattern below:

{NOTATION_CONFIG}/truststore/{trust-store-type}/{named-store}/{cert-file}

Trust Policy

Developers can create a trust policy to verify artifact signatures from a registry. A trust policy is a policy language which specifies which identities are trusted to validate an artifact signature and the level of signature verification to be used. Typically, a trust policy is written in JSON and located within the notation configuration directory.

The path of the Trust Policy file is as follows.

{NOTATION_CONFIG}/trustpolicy.json

Signing Key Store

Developers sign artifacts using local private keys with associated certificate chain. The signing key information is tracked in a JSON file at:

{NOTATION_CONFIG}/signingkeys.json

The signing key store is user-specific. Developers SHOULD consider safe places to store the passphrase-protected key and certificate pairs, or opt to remote signing.

For testing purpose, the following directory structure is suggested.

{NOTATION_CONFIG}/localkeys/{key-name}.crt
{NOTATION_CONFIG}/localkeys/{key-name}.pem

Since signingkeys.json takes references in absolute paths, it is not required to copy the private keys and certificates used for signing to the above directory structure.

Caches

Since Notation v1.3.0, CRL files are cached by default to reduce network traffic to the CRL server, thereby minimizing potential server throttling and enhancing performance with lower latency. The path of cached CRLs follows the pattern below.

{NOTATION_CACHE}/crl/{sha256-hash-of-the-CRL-downloading-URL}

Examples

Examples are shown on various operating systems where the user exampleuser overrides the notation config, cache and the trust policy.

Unix

/
└── home
   └── exampleuser
   └── .cache
   | └── crl
   | ├── f2ca1bb6c7e907d06dafe4687e579fceceae8f2e6b6b8bdf0abdd33b264e9a0e
| └── 05b3abf2579a5eb66403cd78be557fd860633a1fe2103c7642030defe32c657f
   └── .config
   └── notation
   ├── config.json
   ├── localkeys
   │   ├── dev.crt
   │   ├── dev.pem
   │   ├── test.crt
   │   └── test.pem
   ├── plugins
   │   └── com.example.bar
   │   └── notation-com.example.bar
   ├── signingkeys.json
   ├── trustpolicy.json
   └── truststore
   └── x509
   ├── ca
   │   └── acme-rockets
   │   └── cert4.pem
   └── tsa
   └── publicly-trusted-tsa
   └── tsa-cert2.pem

Windows

C:.
└── Users
└── exampleuser
└── AppData
├── Local
│ └── notation
   │ └── crl
   │ ├── f2ca1bb6c7e907d06dafe4687e579fceceae8f2e6b6b8bdf0abdd33b264e9a0e
│ └── 05b3abf2579a5eb66403cd78be557fd860633a1fe2103c7642030defe32c657f
└── Roaming
└── notation
├── config.json
├── localkeys
│   ├── dev.crt
│   ├── dev.pem
│   ├── test.crt
│   └── test.pem
├── plugins
│   └── com.example.bar
│   └── notation-com.example.bar.exe
├── signingkeys.json
├── trustpolicy.json
└── truststore
└── x509
├── ca
│   └── acme-rockets
│   └── cert4.pem
└── tsa
└── publicly-trusted-tsa
└── tsa-cert2.pem

Darwin / macOS

/
└── Users
   └── exampleuser
   └── Caches
   | └── crl
   | ├── f2ca1bb6c7e907d06dafe4687e579fceceae8f2e6b6b8bdf0abdd33b264e9a0e
| └── 05b3abf2579a5eb66403cd78be557fd860633a1fe2103c7642030defe32c657f
   └── Library
   └── Application Support
      └── notation
      ├── config.json
      ├── localkeys
      │   ├── dev.crt
      │   ├── dev.pem
      │   ├── test.crt
      │   └── test.pem
      ├── plugins
      │   └── com.example.bar
      │   └── notation-com.example.bar
      ├── signingkeys.json
      ├── trustpolicy.json
      └── truststore
      └── x509
      ├── ca
      │   └── acme-rockets
      │   └── cert4.pem
      └── tsa
      └── publicly-trusted-tsa
      └── tsa-cert2.pem

Docs: Troubleshooting

Mon, 01 Jan 0001 00:00:00 +0000

Important

To suggest a troubleshooting item, create a pull request PR with your suggested item

How do I troubleshoot issues with signatures?

oras manifest fetch fetches information about an artifact; such as mediatype, config, layers, and annotations. By using the --descriptor flag, you can fetch only the descriptor of an artifact. Inspect the descriptor of a remote artifact sent for signing using oras manifest fetch --descriptor. For example:

$ oras manifest fetch --descriptor IMAGE:TAG
{"mediaType":"...","digest":"sha256:...","size":...}

Confirm the details, such as the mediaType and digest match the details of the artifact sent for signing.

Inspect the signatures of a remote artifact using notation inspect with the digest value for the artifact. For example:

$ notation inspect localhost:5001/net-monitor@sha256:cae906b84806687f02272d00a7000ff31a6be6281bb72f16bdef2fcd67d41786
Inspecting all signatures for signed artifact
localhost:5001/net-monitor@sha256:cae906b84806687f02272d00a7000ff31a6be6281bb72f16bdef2fcd67d41786
└── application/vnd.cncf.notary.signature
├── sha256:1bf07b33089e65e9e83a780c7f405ba36aa4ef2b2fb031535cc6e89042ac0a0f
│ ├── media type: application/jose+json
│ ├── signature algorithm: RSASSA-PSS-SHA-256
│ ├── signed attributes
│ │ ├── signingScheme: notary.x509
│ │ └── signingTime: Sun Jun 11 19:56:47 2023
│ ├── user defined attributes
│ │ └── (empty)
│ ├── unsigned attributes
│ │ └── signingAgent: Notation/1.0.0
│ ├── certificates
│ │ └── SHA256 fingerprint: 3f32321edede5df5bb02e88749217ef10c6c4ce8a5d62bb2136257a0ade6e832
│ │ ├── issued to: CN=wabbit-networks.io,O=Notary,L=Seattle,ST=WA,C=US
│ │ ├── issued by: CN=wabbit-networks.io,O=Notary,L=Seattle,ST=WA,C=US
│ │ └── expiry: Mon Jun 12 18:56:09 2023
│ └── signed artifact
│ ├── media type: application/vnd.docker.distribution.manifest.v2+json
│ ├── digest: sha256:cae906b84806687f02272d00a7000ff31a6be6281bb72f16bdef2fcd67d41786
│ └── size: 942
└── sha256:e503cadaa2ffee0272acc8ec1dcb4f737a7245b01491e86b9a382ca3fed88297
├── media type: application/cose
├── signature algorithm: RSASSA-PSS-SHA-256
├── signed attributes
│ ├── signingScheme: notary.x509
│ └── signingTime: Sun Jun 11 19:57:14 2023
├── user defined attributes
│ └── (empty)
├── unsigned attributes
│ └── signingAgent: Notation/1.0.0
├── certificates
│ └── SHA256 fingerprint: 3f32321edede5df5bb02e88749217ef10c6c4ce8a5d62bb2136257a0ade6e832
│ ├── issued to: CN=wabbit-networks.io,O=Notary,L=Seattle,ST=WA,C=US
│ ├── issued by: CN=wabbit-networks.io,O=Notary,L=Seattle,ST=WA,C=US
│ └── expiry: Mon Jun 12 18:56:09 2023
└── signed artifact
├── media type: application/vnd.docker.distribution.manifest.v2+json
├── digest: sha256:cae906b84806687f02272d00a7000ff31a6be6281bb72f16bdef2fcd67d41786
└── size: 942

The output contains all the certificate information used for signing the artifact. You can use this information to validate the signing certificates and certificate chain.

The output also contains details about the artifact that was signed, such as the digest. You can use this information to confirm that the correct artifact was signed.

For more information about signatures and their components, see the Notary signature specification.

Enabling notation CLI commands logging

To troubleshoot issues with the notation CLI, you can use the --verbose or -v flag for more detailed logging. Using the --verbose flag gives more detailed information about the notation CLI command. This is useful in identifying and resolving issues effectively.

Use the --verbose flag to enable verbose logging when running a notation CLI command. For example:

notation verify --verbose localhost:5000/net-monitor@sha256:xxx

In addition, there is --debug, which is intended for developers to debug the notation CLI. It is not recommended to use --debug for end-user troubleshooting.

When I verify an artifact, I get the error ‘Error: open $HOME/.config/notation/trustpolicy.json: no such file or directory’

This error is likely related to trust policy configuration. Verify you have a trust policy set up before you attempt to verify an artifact. notation policy show can be used to view the current trust policy in use. If you need to override an existing trust policy with a new one, you can use the notation policy import command to import a new trust policy. For more details, see Manage trust policies

When I verify an artifact, I get the error ‘"$HOME/.config/notation/ truststore/x509/ca/mytruststore" does not exist’

This error indicates the trust store doesn’t exist or the trust store name is not correct. Trust store typically contains a set of certificate files, where the trust identities are retrieved to verify signatures. You can use notation cert add to add trust stores.

The above error shows that the type of trust store is ca, and the trust store name is mytruststore. Aside ca trust store type, X.509 also supports other types of trust stores such as, the x509/signingAuthority and x509/tsa. For more details, please refer to the trust store and trust policy specification

To verify ca and mytruststore exist, use notation cert list, then confirm whether the type of store ca and store name mytruststore are in the list with the right certificate file stored.

If ca and mytruststore are not in the list, use notation cert add to add them. For example:

notation cert add --type ca --store mytruststore mycertfile.crt

When I verify an artifact, I get the error ‘signature is not produced by a trusted signer’

Assuming the trust store and trust policy are configured correctly, this is a verification failure and that artifact should not be used.

Specifically, this error indicates that the artifact is signed by an unknown identity, which should not be trusted, based on the trust policy. In this case, the verification should fail and users should not use the artifact.

To confirm the trust store and trust policy are configured correctly:

If you have multiple trust policies in trustpolicy.json file, confirm you are using the correct trust policy for this artifact by running notation policy show. This will display information about the trust policy used for verifying the artifact.
Check the trustStores property and confirm the value is correctly configured.
Check the trustedIdentities property and confirm the value is correctly configured.

If the value is "*", it means all the certificates stored in the trust stored (configured in trustStores) are trusted. then you need to make sure the certificates in the trust stores can be used to verify the signatures.
If the value is in the format of x509 subject info, like "x509.subject: CN=example.io,O=Notary,L=Seattle,ST=WA,C=US", then you need to make sure it is the identity that produces the signature.

Use notation cert show to show the details of the certificate in the trust store. For example:

notation cert show --type ca --store mytruststore mycertificate.crt

An example of output:

Certificate details
--------------------------------------------------------------------------------
Issuer: CN=example.io,O=Notary,L=Seattle,ST=WA,C=US
Subject: CN=example.io,O=Notary,L=Seattle,ST=WA,C=US
Valid from: 2023-06-22 08:33:39 +0000 UTC
Valid to: 2023-06-23 08:33:39 +0000 UTC
IsCA: false
SHA256 Thumbprint: 3ab41b683b24b40abfa87c1fe26c81b917a9ccc1c4bf60f90e2b41deb86f5220

Check the Subject info in the output. If it is the identity that signs the artifact, you need to add the Subject info into trustedIdentities.

When I verify an artifact, I get the error ‘signature verification failed for all the signatures associated with ${IMAGE}’

This is an expected error message when all the signatures associated with ${IMAGE} are not trusted. If all signatures are trusted, it may be one of the following issues:

Not having a trust store configured or the trust store is not configured correctly.
Trust store is not readable or the certificates stored in the trust store are not readable
No certificates were stored in trust store

Rerun the verify command with --verbose to get more details.

The following example shows the trust store mystore has not be configured correctly or can’t be found:

$ notation verify $IMAGE --verbose
...
ERRO authenticity validation failed. Failure reason: error while loading the trust store, "/home/USER/.config/notation/truststore/x509/ca/mystore" does not exist
WARN Signature sha256:11223344556677889900aabbccddeeff11223344556677889900aabbccddeeff failed verification with error: error while loading the trust store, "/home/USER/.config/notation/truststore/x509/ca/mystore" does not exist
Error: signature verification failed for all the signatures associated with localhost:5001/net-monitor@sha256:000999888777666555444333222111fffeeedddcccbbbbaaa000999888777666

The following example shows the certificate mystore.crt in the mystore trust store could not be accessed:

notation verify --v $IMAGE
...
ERRO authenticity validation failed. Failure reason: error while loading the trust store, error while reading certificates from "/home/USER/.config/notation/truststore/x509/ca/mystore/mystore.crt": open "/home/USER/.config/notation/truststore/x509/ca/mystore/mystore.crt": permission denied
WARN Signature sha256:11223344556677889900aabbccddeeff11223344556677889900aabbccddeeff failed verification with error: error while loading the trust store, error while reading certificates from "/home/USER/.config/notation/truststore/x509/ca/mystore/mystore.crt": open /home/USER/.config/notation/truststore/x509/ca/mystore/mystore.crt: permission denied
Error: signature verification failed for all the signatures associated with localhost:5001/net-monitor@sha256:000999888777666555444333222111fffeeedddcccbbbbaaa000999888777666

The following example shows that there are no certificates in the mystore trust store.

$ notation verify $IMAGE --verbose
...
ERRO authenticity validation failed. Failure reason: error while loading the trust store, trust store "/home/USER/.config/notation/truststore/x509/ca/mystore" has no x509 certificates
WARN Signature sha256:11223344556677889900aabbccddeeff11223344556677889900aabbccddeeff failed verification with error: error while loading the trust store, trust store "/home/USER/.config/notation/truststore/x509/ca/mystore" has no x509 certificates
Error: signature verification failed for all the signatures associated with localhost:5001/net-monitor@sha256:000999888777666555444333222111fffeeedddcccbbbbaaa000999888777666

I have configured trust policy, but I still get the error ‘no applicable trust policy’

This error indicates that the registryScopes property is not correctly configured. This property contains a list of repository URIs, where the artifacts are stored. Verify the signing artifact is stored in one of the listed repositories. If not, add the missing repository URI in registryScopes, or you can add a new trust policy for the missing repository.

The repository URI is in the format of ${registry-name}/${namespace}/${repository-name}. For example, if the artifact to be verified is registry.acme-rockets.io/software/net-monitor@sha256:xxx, then the value for registryScopes should be registry.acme-rockets.io/software/net-monitor.

The following values are not correct:

registry.acme-rockets.io
registry.acme-rockets.io/software

Important

Wildcards are not supported in registryScopes property. Each repository URI should be listed explicitly.

When I verify an artifact, I get the error ‘malformed trustpolicy.json file’

This is usually an encoding problem of trustpolicy.json file. Notation expects utf-8 without BOM or ascii encoding for trustpolicy.json file.

Windows PowerShell (prior to v6) uses the Unicode UTF-16LE encoding by default, and utf-8 without BOM is not supported. If you are building trustpolicy.json file in Windows PowerShell (prior to v6), make sure you change the file encoding to ascii.

When I verify an artifact, I get the error ‘Failed to unmarshal the payload content in the signature blob to envelope.Payload’

This is usually an encoding problem of payload content in the signature envelope. Notary Project signatures can be produced by different tools per signature specification. The payload content is a JSON document defined in the signature specification, and the encoding should be utf-8 without BOM or ascii.

Windows PowerShell (prior to v6) uses the Unicode UTF-16LE encoding by default, and utf-8 without BOM is not supported. If you are building payload content in Windows PowerShell (prior to v6), make sure you change the payload content encoding to ascii.

Docs: Glossary

Mon, 01 Jan 0001 00:00:00 +0000

Notary Project

The Notary Project refers to the GitHub organization, the community, all specifications, and all the repositories under the GitHub organization, including community-released tools like notary and notation.

Notary

Notary is a TUF (The Update Framework) based artifact signing implementation. It consists of a server and client components. The server infrastructure tightly integrates with the container registry and keeps track of the images pushed to the registry. The client component is referred to as the notary command-line interface (CLI), which handles tasks such as signing and pushing container images to a registry and updating metadata. The CLI communicates with the registry and the key and metadata management server component. The most prominent use of this implementation is in Docker Content Trust (DCT). The server and the client implementation can be found in the notary repository under the Notary Project organization.

Notation

Notation, based on new set of specifications unrelated to TUF, is a newer implementation from the Notary Project. It refers to the implementation of the Notation CLI and the Notation libraries. Notation offers signing and verification workflows for OCI artifacts, enables signature portability across OCI-compliant registries, and facilitates integration with third-party key management solutions through a plugin model. The CLI itself is referred to as the Notation CLI while the libraries are referred to as the Notation-Go library and the Notation-Core-Go library. Stakeholders can use libraries independently of the Notation CLI for integrating Notation with their own client tools.

Notary Project Specifications

Notary Project Specifications, mainly created between years 2021-2022, are a collection of specifications distributed across “subprojects” within the Notary Project. Notation CLI and libraries have implemented these specifications, which are also utilized by other OSS projects and/or vendor tools that seek to interoperate with the Notary Project tooling. These specifications are stored in the specifications repository under the Notary Project.

Notary Project specifications are categorized into:

OCI Signature Specifications: These specifications are specific to the Open Container Initiative (OCI). It describes how the Notary Project’s Signing Scheme is applied to signatures stored in OCI registries. This category includes the following specifications:

Signing Scheme Specification: The Signing Scheme Specification is not specific to any particular storage method. It describes the supported signing schemes. Any tool that supports those schemes might be able to produce signatures that are compatible with Notary Project tools. The specification under this category includes the Notary Project Signing Scheme.

TUF

TUF refers to The Update Framework. A tuf repository under the Notary Project organization is intended for prototyping the storage of TUF metadata in OCI-compliant registries. It is not under active development at the moment.

Docs: Verification of container image on Kubernetes

Mon, 01 Jan 0001 00:00:00 +0000

As container images continue to be distributed across various channels, it becomes increasingly important for consumers to ensure that the downloaded container images are authentic before deploying them into their Kubernetes environment. This practice helps mitigate potential cyber threats. Container image verification is the process of evaluating the digital signature of a container image to determine if a container image is considered authentic. Let’s say, you’ve downloaded a signed image from a public source for deployment within your Kubernetes cluster. How do you validate the authenticity and integrity of the image? Which tools should you use for verifying signed images during deployment? This guide describes verification scenarios on Kubernetes and suggests tools for validating signed container images before deploying them on Kubernetes. Let’s take a look at this scenario in more detail:

Verification Scenario on Kubernetes

This scenario describes a series of steps that a software publisher and consumer go through to ensure the integrity of a software package.

The software publisher builds and pushes an application to a container registry such as Docker Hub. This process results in the creation of a container image. Before making the container image accessible to the public, the software publisher uses the Notation Command Line Interface (CLI) to generate cryptographic keys for signing the image. These keys consist of a private key for creating a digital signature and a corresponding public key for image verification.

After signing the image, it gets uploaded to a public repository such as GitHub Packages, using the OCI Registry As Storage (ORAS) command line tool. Potential users are required to verify the image before using it. Users can use the Notation CLI to validate the signature digest and inspect the signature along with its certificate information to confirm the image’s authenticity. However, an additional layer of security is applied to validate images before deployment on Kubernetes. Users can use any Open Policy Agent (OPA) or admission controller of their choice to define and enforce policies to ensure images meet established security and authenticity criteria. The admission controller operates on specified policies to validate image deployment on Kubernetes. If the image is signed by a trusted source, it admits the image into Kubernetes resources, ready for deployment. However, if the image is unsigned or does not pass the authenticity check, its deployment gets blocked, preventing any potentially malicious or tampered images from being deployed into the Kubernetes cluster.

The following solutions can be used to verify signed container images before deployment on Kubernetes:

Ratify and OPA GateKeeper

Within your Kubernetes environment, OPA Gatekeeper can be utilized as the admission controller for defining policies that artifacts must adhere to, alongside Ratify, to validates the admission of only signed images for deployment. Refer to this article on how to Sign and verify an image with Notation, Ratify, and OPA Gatekeeper.

Kyverno

Kyverno is a policy engine designed for Kubernetes. It allows users to generate Kubernetes policies to validate, mutate, generate, and clean up Kubernetes resources, and verify image signatures and artifacts to help secure the software supply chain.

Docs: Notary Project Adopters

Mon, 01 Jan 0001 00:00:00 +0000

The following organizations are known adopters who use Notation in production or integrate Notation into their products and services.

We are happy and proud to have you all as part of the community! To add your use case and organization to this list, please raise a pull request.

All organizations are sorted alphabetically below.

Organization	Website	Scenario
Alibaba Cloud	https://www.alibabacloud.com/	Sign and verify OCI artifacts using Notation and Alibaba Cloud Key Management Service
Amazon	https://aws.amazon.com/	AWS Signer
Bitnami	https://bitnami.com/	Sign and verify containers and Helm charts available in Docker Hub
containerd	http://containerd.io/	container image sign and verify with notation tool
Connaisseur	https://github.com/sse-secure-systems/connaisseur	Verify container images signed with Notation when deploying them to Kubernetes
Harbor	https://goharbor.io/	Storage and display Notary Project signature
Kyverno	https://kyverno.io/	Support verifying Notary Project signature
Microsoft	https://www.microsoft.com/	Build, sign, and verify container images using Notation and Azure Key Vault
Ratify	https://ratify.sh/	Validating OCI Artifact signatures using Notation library
Tanzu Application Catalog	https://tanzu.vmware.com/application-catalog	Sign and Verify OCI artifacts (e.g. Helm charts, container images, and metadata bundles
Venafi	https://venafi.com/codesign-protect/	Sign and Verify container images using Notation and Venafi CodeSign Protect
Nomad Admission Control Proxy	https://github.com/mxab/nacp	Uses `notation-go` remote verify to validate images when deploying Nomad Jobs
KubeStellar	https://console.kubestellar.io	Guided Ratify install mission with automated Gatekeeper + Ratify deployment, signature verification testing, and AI-powered troubleshooting across multi-cluster Kubernetes fleets

Docs: Registry support

Mon, 01 Jan 0001 00:00:00 +0000

The following registries, listed in alphabetical order, support Notary Project OCI signatures:

Docs: Timestamping

Mon, 01 Jan 0001 00:00:00 +0000

In the X.509 Public Key Infrastructure (PKI) system, digital signatures must be generated within the certificate’s validity period, as expired certificates compromise the signature’s trustworthiness. The RFC 3161 standard defines the internet X.509 PKI Time-Stamp Protocol (TSP), where a timestamp is issued by a trusted third party acting as a Time Stamping Authority (TSA). These trusted timestamps extend the trust of signatures created within certificates validity, enabling successful signature verification even after certificates have expired.

Since Notation v1.2.0 release, Notation supports RFC 3161 compliant timestamping. During signing, a timestamp countersignature is added to the Notary Project signature envelope for the signing artifact, ensuring the trustworthiness of the signature through validation. However, Notation does not use timestamp to verify that the signature was created before any certificate revocation, as the revocation time is not deterministic. For example, the revocation time may not coincide with the time the certificates are compromised.

This guide describes how to sign and verify artifacts in OCI (Open Container Initiative) compliant registries with timestamping. Artifacts in OCI-compliant registries can be container images or other artifacts such as Software Bill of Materials (SBOM).

Prerequisites

Before starting, ensure you have:

Learned the basic signing and verification workflow following the guide since Timestamping feature was added on top of existing signing and verification workflows.
Installed Notation CLI v1.2.0. If not, follow the installation guides.
Installed Notation plugins for signing with keys stored in a KMS (Key Management System), such as Azure Key Vault.
A container image or artifact stored in an OCI-compliant registry.

Sign artifacts in OCI-compliant registries with timestamping

To sign artifacts in OCI-compliant registries with timestamping, you need to select a trusted RFC 3161 compliant TSA. There are public TSAs available, such as DigitCert TSA and Globalsign TSA. Since Notation CLI v1.2.0, two flags --timestamp-url and --timestamp-root-cert are introduced to the notation sign command for RFC 3161 timestamping. Use the flag --timestamp-url to specify the URL of the TSA that you trusted. Use the flag --timestamp-root-cert to specify the filepath of downloaded root cert file for the trusted TSA. The root cert serves as the trust anchor to establish the chain of trust of the TSA. This is to protect you from MITM (Man-in-the-Middle) attacks. Upon successful execution of notation sign, the TSA response will be stored in the signature envelope. An example command:

notation sign --timestamp-url <TSA_URL> --timestamp-root-cert <TSA_ROOT_CERT> --key <KEY_NAME> <REFERENCE_TO_ARTIFACT>

For example, if you choose DigiCert public TSA, the URL is http://timestamp.digicert.com, and you can download the root certificate here and name it as digicert_root_cert.crt. The command looks like:

notation sign --timestamp-url "http://timestamp.digicert.com" --timestamp-root-cert "digicert_root_cert.crt" --key <KEY_NAME> <REFERENCE_TO_ARTIFACT>

If you do not specify the two flags --timestamp-url and --timestamp-root-cert, artifacts are signed without timestamping.

Inspect signatures with RFC 3161 timestamp

Since Notation v1.2.0, the notation inspect command is enhanced to show RFC 3161 timestamp in the output.

notation inspect <REFERENCE_TO_ARTIFACT>

An example output:

├── unsigned attributes
│ ├── timestamp signature
│ │ ├── timestamp: [Tue Aug 20 00:14:59 2024, Tue Aug 20 00:14:59 2024]
│ │ └── certificates
│ │ ├── SHA256 fingerprint: d2f6e46ded7422ccd1d440576841366f828ada559aae3316af4d1a9ad40c7828
│ │ │ ├── issued to: CN=DigiCert Timestamp 2023,O=DigiCert\, Inc.,C=US
│ │ │ ├── issued by: CN=DigiCert Trusted G4 RSA4096 SHA256 TimeStamping CA,O=DigiCert\, Inc.,C=US
│ │ │ └── expiry: Fri Oct 13 23:59:59 2034
│ │ ├── SHA256 fingerprint: 281734d4592d1291d27190709cb510b07e22c405d5e0d6119b70e73589f98acf
│ │ │ ├── issued to: CN=DigiCert Trusted G4 RSA4096 SHA256 TimeStamping CA,O=DigiCert\, Inc.,C=US
│ │ │ ├── issued by: CN=DigiCert Trusted Root G4,OU=www.digicert.com,O=DigiCert Inc,C=US
│ │ │ └── expiry: Sun Mar 22 23:59:59 2037
│ │ └── SHA256 fingerprint: 33846b545a49c9be4903c60e01713c1bd4e4ef31ea65cd95d69e62794f30b941
│ │ ├── issued to: CN=DigiCert Trusted Root G4,OU=www.digicert.com,O=DigiCert Inc,C=US
│ │ ├── issued by: CN=DigiCert Assured ID Root CA,OU=www.digicert.com,O=DigiCert Inc,C=US
│ │ └── expiry: Sun Nov 9 23:59:59 2031

Under the field timestamp signature, there are timestamp and certificates fields. The value of certificates lists all the certificates included in the TSA response.

Verify artifacts in OCI-compliant registries with timestamping

To verify artifacts in OCI-compliant registries with timestamping, you need to create a trust store with the type of tsa, add the downloaded TSA root certificate, and use the trust store in the trust policy for verification.

Here are the steps:

Create the trust store with the type tsa:

notation cert add --type tsa --store <TSA_STORE_NAME> <TSA_ROOT_CERT_FILEPATH>

Update your trust policy to add the tsa trust store to the property trustStores.

{
"version": "1.0",
"trustPolicies": [
{
"name": "<POLICY_NAME>",
"registryScopes": [ "<REPO_URL>" ],
"signatureVerification": {
"level" : "strict"
},
"trustStores": ["ca:<CA_STORE_NAME>", "tsa:<TSA_STORE_NAME>" ],
"trustedIdentities": [
"x509.subject: <SUBJECT_OF_SIGNING_CERT>"
]
}
]
}

Import and use the new trust policy:

notation policy import <POLICY_FILE_NAME>.json

Verify artifacts, optionally you can use flag -v to view the verbose logs:

notation verify -v <REFERENCE_TO_ARTIFACT>

If the signature was generated with timestamping before certificates expiry, the signature verification will succeed despite certificates expiry at verification time. However, if the trust store of the tsa type is not properly established or not configured within the trust policy, the signature verification will fail due to certificates expire.

Configuration for timestamp verification

By default, if the trust store of tsa type is created and configured in the trust policy, Notation will always perform timestamp verification no matter the certificates expire or not. In scenarios you may want to perform timestamp verification only after certificates expire, you can configure additional property verifyTimestamp under the parent property signatureVerification and set the value to afterCertExpiry in the trust policy. For example,

{
"version": "1.0",
"trustPolicies": [
{
"name": "<POLICY_NAME>",
"registryScopes": [ "<REPO_URL>" ],
"signatureVerification": {
"level" : "strict",
"verifyTimestamp": "afterCertExpiry"
},
"trustStores": ["ca:<CA_STORE_NAME>", "tsa:<TSA_STORE_NAME>" ],
"trustedIdentities": [
"x509.subject: <SUBJECT_OF_SIGNING_CERT>"
]
}
]
}

To restore to the default behavior, you can either remove the property verifyTimestamp, or set the value to always.

What is the next?

In the future, we’ll use the system certificate store to verify the chain of trust of a TSA, eliminating the need for you to download and use the root certificate.

Community: Notary v2 Meeting Notes Archive - 2019

Mon, 01 Jan 0001 00:00:00 +0000

Notary v2 Kickoff Meeting

December 12, 2019

Agenda

Time	Agenda
10:00-10:30	Arrival
10:30-10:45	Welcome & intros
11:00-11:20	Goals for the meeting
11:20-11:45	Goals for Notary v2
11:45-12:30	Requirement discussion
12:30-01:00	Lunch
01:00-03:00	Open Discussions TBD
03:00-03:30	House Keeping/Next Steps
03:30-05:00	Unbooked, as some have previous committments
06:00-??:??	Dinner downtown seattle (location tbd)

Dinner (location tbd. Please reply with any dietary restrictions for lunch and dinner)

Attendees

Steve Lasker (Microsoft acr/mcr)
Sajay Antony (Microsoft acr/mcr)
Shiwei Zhang (Microsoft acr/mcr)
Ralph Squillace (Microsoft)
Radu Matei (Microsoft)
Samuel Karp (AWS / container runtimes)
Jay Pipes (aws eks)
Raja (aws ecr/hybrid)
Tue (aws / ecr)
Lahiru (aws / ecr)
Vincent Batts (red hat)
Jon Johnson (google)
Omar Paul (aws - product manager ecr)
Lindsay Smith (google gcr)
Lukasz Opyrchal (google gcr)
Derek McGowan (docker)
Michael Hasuenblaus (aws)
Michael Brown (OCI/IBM)
Miloslav Trmac (RedHat)
Joey (quay)
Hank (quay)
Kenny (quay)
Evan (quay)
Maria Moore (NYU)
Justin Cormack (Docker)
Chad Metcalf (Docker)
Kat (JFrog)

Meeting Notes

Video of the discussions

https://youtu.be/mZ_x0KW33Tg (all three segments combined)

Goals for the meeting

Round table discussion
Justin - Identify areas of focus

Goals for notary v2

Reading/reference material
Notary v2 Google Doc from Justin
Artifacts Signing Requirements
Previous discussion in opencontainers/image-spec
- #22, #176, #480
Support up/down the stack, inlcuding K8s, and other container hosts
Consistency across registry operators
SteveLas - Each cloud can point customers to a central oss/notary location for general documentation, then each cloud only needs to provide their unique interaction, such as auth or how the info is displayed
SteveLas - each cloud has the ability to utilzie their specific providers, such as auth and key storage. The spec would provide a common api for customers, but the underlying interaction would be open. Just as ddocker-distribution enables cloud specifi
Justin - Consistency of signatures, movement between repos as well as cross registry
Joey - the simpler we can keep things, the more likely we can all standardize on tooling, now
Steve - How much do we need to save compat on previous notary/content trust is a good question
Vincent - reusing infra for existing, should be a goal
Justin - keeping signatures in the registry, so it’s not separate components for clouds/vendors to implement
Joey - if you can use arbitray mime types, keeping the signature in the registry is helpful. Can leverage caches, like the kube image cache
SteveLas - should we support signatures in the registry, for artifacts that are stored externally?
Radu - storing signatures inside the registry, but the CNAB is stored outside the registry is a requirement for air-gapped environment
Joey - if manifest lists can reference an external entity, will that suffice? (internal/external references)
Radu - the entity that is signed, needs to reference the content digest that’s stored in the registry (Radu - please correct this note)
Vincent - should have a means to deal with compression and decompression scenarios.
Vincent - You should sign the opaque blob. How a registry, or transport handles compression is a separate element
SteveLas - signature movement/copy must be fully copied into the destination environment. Users within the air-gapped enviornment must be able to self validate the signature wihtin that air-gapped environment
Justin - how do we get the public keys between environments?
Marina - As long as the initial root of trust is good, the destination shouldn’t matter.
Miloslav - if an ISV signs an artifact, that should be maintained (if consumers have public keys directly from the ISV, don’t allow a registry to sign on-behalf)
- Some signatures may not move, rather stay in their source.
- “please lets not re-invent the Certificate Authority ecosystem”
Justin - with Docker Hub, there’s currently too many keys as each repo can have it’s own key.
Justin - vendors should have the ability to have a single key to represent all their images, rather than each artifact having their own
evan - registry keys vs repo keys, and having a hierarchy
Vincent - should their be a tiered level of trust between certs?
SteveLas - how do we enable clients/nodes to support signatures? Is this a policy? Do we need to incorporate the flow into K8s and other container hosts?
Justin - when should the signature be verified. If you use a tag, is it late binding?
Vincent - assumed it would be more like the admission controller scneario
Raja - at the cluster - should it determine based on a dev or production environment. The same application/same image might have different policies, based on the environemnt
Vincent - should be pre-flight validation capable
Vincent - revocation/ejection of artifacts for comprimised certs
Raja - how do we handle revocation across air-gapped registries
Vincent - can we do multiple signatures, as it moves across the workflow?
Justin - signatures through the CI flow.
Steve - signatures by scanning solution, to say it’s been security signed
Vincent - multiple signatures might something we can do later
Tue - can we do signatures on the base layers?
Vincent - this scenario was supported in Docker 1.8?, and we’d have to revisit to bring it back.
Joey - can we sign the signed manifest with another signature? Tuf may have a solution for threshold signatures. If we’re concerned about multiple sigs, we should be able leverage what’s already there (TUF)
Raja - should each layer have different pointers.
Steve - this could help with the base image vulnerabilities issues
Vincent - need to account for the squash scenarios
Miloslav - for multi-signatures, need to think about two different roots of trust (!= TUF threshold signing)
Miloslav - manifest digests are used for things like openshift, to assure consistency. We should make sure the signature doesn’t change the digest.
Vincnet - you can have manifest lists, point to additional manifest lists. Clients could hop through the manifest lists.
Lindsay - what does it mean for a registry to sign content? How do signatures flow through registries if a registry doesn’t support signing?
Justin - It doesn’t make sense for the registry to sign artifacts. The client should sign it. Where they do signing is a different question.
Joey - as long as we have the necessary hooks, for cloud, or external cloud hsm providers.
Raja - what does multi-tenancy look like. An org with multiple subsidearies.
SteveLas - Should a distribution spec incorporate multi-tenancy for storing multiple customer keys
Justin - how does mirroring work in these scenarios?
Joey - if built atop distirbution, handling multi-tenancy already, there shouldn’t be any additional work, other than handling heirarchical root keys
- idealiy, there’s a way for the protocol to know a root key, for a tenant, is located at this place. The registry could have a root key.
Marina - could this be handled with delegation?
Justin - when discussing docker hub, if you did root at the org, it could like repo inormation. You might be able to pull the tuf metadata to get all the repos. Changed at the last minute. Should revisit the concerns.
Evan - There’s an extension to TUF to explain how to disambiguate public and private.

Client Experience/Requirements

Justin Signing should be built into everything. It shouldn’t have to be a seperate tool
Joey - docker made containers avaialble to the world, becuase the experiences were frictionless and consolidated.
Samuel - the challenge with it only being built in, doesn’t allow for different trust policies. What if I wanted to express different expiration dates.
Justin - can there be a plug-in model?
Samuel - use case - I want to provide a trust policy to a cluster, where do I define this for prod vs. staging.
Samuel - I don’t want to put all the policy information into the client.
Justin - should there be a default/normal policy.
Steve - should the plug-in model be at the registry as well, to enforce policies, before the image is even pulled.
Joey - preventing pulls, outside of auth are overly restrictive.
Sajay - Notary is currently a different endpoint. Should the notary server be separate? This causes vnet/firewall rule challenges
Justin - Registry should have this part of the endpoint.
Steve - Capabilties - how can a registry support a set of capabiliites that it supports, as opposed to having a strict versoin MUST list.
Joey - TAP, based on python supports a feature discovery scenario
Should add this capabilities/discovery approach to distribution, as a base, as part of v1?
- Vincent - as long as it doesn’t take too long
Justin - should standardize a set of annotations for signing
MikeBrown - reminder for existing annotation rules and predefined examples:
- https://github.com/opencontainers/image-spec/blob/master/annotations.md#annotations
Justin - probably need a breakout for threat model.
Tue - some customers may want the registry to provide a managed signing solution (whether it does it itself and/or hands that off to a service such as aws KMS).
Omar - when launching workloads across many nodes, should make sure the design does not prevent a way for a control plane or node to verify prior to pulling the entire image. (e.g. revoked, check publisher)
Joey - lets not solve key distribution as part of all this. API can return a redirect to go ‘here’ to verify/manage keys, lets key management be part of the orchestrator, for example.
Mike - manage pull policy from the pod spec in kubelet. +1 to the point above, the container runtime nor the registry implements policy, e.g. running verified images.
Justin - make sure out-of-band key management does not cause a ‘million’ keys to exist and be used in signing and verifying
Sam - Cannot really have a system to allow trust without having a way to also signify mistrust.
Justin - experience from v1 was not as optimal as what docker trust laid out, that may be a model for how the cli looks like (as a starting point). E.g. observability of the signature was not good.
Steve, Sajay - Most of our support cases are around usability today. Must make this simple to use for clients.

Breakout Conversations

How compression/decompression is handled with signatures
What do signatures look like witihin a registry
- Justin - Detached signatures?
Use case/test cases
Policy plug-ins
- Client plug-ins
- Registry plug-ins
- Does a registry provide a way for clients to pull in policy plug-ins to avoid a client from implmeenting a rogue plug-in?
Annotations and how do we think about a registry and client understanding a signature
Key Management
Signature Storage (OCI, etc)
Threat model
UX (cli, api, params)

Signature Storage

Justin - do people want x509, pki?
Marina - should be careful about providing too many options
Vincent - if I push an opaque sig to a registry, there’s certain things that can be encoded, but there’s data that’s signed in it, and data that’s attached to it (hints). Some things must be wrapped up underneath the signature.
Steve - how can we have a set of annotations that aren’t required to be signed
open discussion - any non-signed metadata is externally tracked, not part of this signing solution.
Open discussion - mutation - for notary v2, we’ll focus on signing a specific object. Tracking it’s history is not part of this scope. If someone takes a signed artifact, makes some change, inlcuding annotations, they can re-sign it, but we’re not worrying about tracking the previous signature.
Justin/Vincent - should focus on signing the checksum of the descriptor, to account for different mediaTypes (artifact types). Note: should follow-up with Derek on some history here.
Justin: annotations should have publisher information.
Vincent - SWID discussion on how it might make sense for storing the signature info
Mike Brown - need to think about how encyrpted content relates to signing

Strawman

Jon - strawman: https://gist.github.com/jonjohnsonjr/6f179e5876118561ca8ed9504e68c9ae

Use Cases

Local Build, Push, Pull, Run

[Must have] Prior to doing any deploymnet, a developer can test the sign, push, run scenario.

Automated Build, Push, Pull, Run

[Must have] A CI/CD solution can be triggered by a git commit. The system can build an artifact, sign it, and push it to the registry. The production system can pull the artifact, verify the signature and run it.

Automated Build, Push, Pull, Failed Run

Multiple runtimes and orchestrators

[Must have] The Automated Build, Push, Pull, Run use case can execute on a Docker, containerd runtime, and in a k8s environment.

Verify base images

[Must have] A CI/CD build system uses base images that are signed. It can verify the signature as part of using them when adding them as layers.

Move images across registry

[Must have] A signed image exists in one registry. I can pull that image and push it into another registry which can validate the signature.

Sign more than just an image

[Must have] A CI/CD system can have a registry that supports more than container images, signs for example a helm chart and stores it in a registry. A client can then verify the chart before using it.

Policy Management

The ability for a cloud provider/vendor to implement a policy managmenet solution

Running a Packaged Product

I can find a product on a public or vendors registry. I can then move the artifact…

Notary v2 Timeline

Omar - we all have pressing timelines. We’ll need a solution we can all implement prior to 2022!
Omar - Conclusion after the kickoff meeting was that we’d have a proposal in time to get a Q4 2020 implementation

House Keeping

Balancing Geo challenges of participants
- occasionaly on-site meetings, with regular conversations on slack
- Use the CNCF Slack:notary v2 for all breakouts
- KubeCon EU on-site meeting? (concern that several key folks wont be able to attend )
  - Arrange on-site meeting at KubeConEU March 30-April 2
  - Justin - we have two 35 min Notary slots
  - For those that do attend KubeConEU, we’ll schedule an afternoon with dial-in for others to attend
  - Steve to arrange logistics (day 0 or +1)
- Will focus on the OCI weekly call for now
- We may schedule one-off calls for specific breakout topics,
- Justin to get a CNCF/Notary zoom room
Where to post community content?
- notary org, although github/notary is taken
- Justin - should assume Notary v2 is a new org, not a branch
- Justin to find a new org
Timeline for notary v2 - setting realistic expectations
- Scope to ship a Notary v2 experience in 2020
Next steps
- breakouts for:
  - Capabilities/PEP for distribtuion-spec (Vincent)
  - Use Cases (Steve) first week of Feb as a working draft
  - Threat Model (Justin)
    - Key Management ()
  - Signature Storage (Vincent/Derek?)
  - UX (Omar)

Dinner/Drinks

for the purposes of security, no notes permitted @ 5:30pm Black Bottle Gastrotavern 2600 1st Avenue Seattle, WA 98121 (206) 441-1500

Community: Notary v2 Meeting Notes Archive - 2020

Mon, 01 Jan 0001 00:00:00 +0000

December 7, 2020

Attendees:

Steve Lasker
David Freilich (VMware)

Agenda Items:

add your topics

Notes:

meeting minutes

November 9, 2020

Attendees:

Steve Lasker (Microsoft)
Niaz Khan (AWS)
Justin Cormack (Docker)
Garry Ing (VMware)
add yourself

Agenda Items:

Review Key Management Requirements (#3 onwards) https://github.com/notaryproject/requirements/pull/38/files?short_path=ce834e0#diff-ce834e0f33c8faa5afad4489d4edf5d224c22ba1e28a5deea73e058ba784bd95

Notes:

meeting minutes

November 2, 2020

Recording

Attendees:

Steve Lasker (Microsoft)
Niaz Khan (AWS)
Furkat Gofurov (Ericsson)
Marco Franssen (Philips - Research)
Marina Moore (NYU)
Jesse Butler (AWS)
Ian McMillan (Microsoft)
add yourself

Agenda Items:

NV2 Demo, focusing on the main end to end (e2e) scenario
- Instnace of distribution hosting prototype changes at nv2.azurewebsites.net. Could be registry.wabbitnetworks.io or registry.acmerockets.io
  - Distribution change docs
  - Distribution change PR#1
  - [Interactive Demo & Review NV2 Prototype](https://github.com/sajayantony/nv2- demo#configurations) (Steve)
Review Key Management Requirements https://github.com/notaryproject/requirements/pull/38/files?short_path=ce834e0#diff-ce834e0f33c8faa5afad4489d4edf5d224c22ba1e28a5deea73e058ba784bd95
add your topics

Notes:

meeting minutes

October 26, 2020

Recording

Attendees:

Steve Lasker (Microsoft)
Marco Franssen (Philips - Research)
Trent Jones (GitHub)
Marina Moore (NYU)
Miloslav Trmač (Red Hat)
Jan Tilles (Ericsson)
Jesse Butler (aws)
Niaz Khan (AWS)
add yourself

Agenda Items:

Review Key Distribution Workflows - Niaz
Client workkflow for TUF proposal
- https://docs.google.com/document/d/1VXrCTyHeLQUJLgMYYRKXYyMQ3kPM0ywGiqiQ7tMxiOg/edit?usp=sharing
add your topics

Notes:

OCI Artifacts & Collections Slides (PowerPoint, PDF)

October 19, 2020

Recording

Attendees:

Steve Lasker (Microsoft)
Justin Cormack (Docker)
Furkat Gofurov (Ericsson)
Marina Moore (NYU)
Sajay Antony (Microsoft)
add yourself

Agenda Items:

Review end to end, build, sign, push, discover, pull of signatures (Steve, Sajay)
- https://github.com/sajayantony/nv2-demo
proposal for using TUF for default/public, while allowing for fine-grained client control for private repos: https://docs.google.com/drawings/d/1lboE1EmbYOKpwRm6sUSrZbKoZD8V6ilo5eHOEAEYizc/edit?usp=sharing
Reminder: Next week, we’ll be 1 hour earlier
add your topics

Notes:

Current prototype - supports at least one key
New policies would support n keys, and specific keys
What are the policies, and how would they be implemented (spec’d)
Demo Script

docker build -t wabbitnetworks.azurecr.io/net-monitor:v1 .
docker notary sign wabbitnetworks.azurecr.io/net-monitor:v1 wabbit-networks.crt
docker notary --enabled
docker push wabbitnetworks.azurecr.io/net-monitor:v1

On a different node (conceptually) with the wabbit-networks key

docker notary --enabled
docker pull wabbitnetworks.azurecr.io/net-monitor:v1

Pull fails, as the key doesn’t exist

az keyvault get-key
docker pull wabbitnetworks.azurecr.io/net-monitor:v1

• Because the key exists, pull succeeds

docker tag wabbitnetworks.azurecr.io/net-monitor:v1 acmerockets.azurecr.io/net-monitor:v1
docker notary sign acmerockets.azurecr.io/net-monitor:v1 acme-rockets.crt
docker push acmerockets.azurecr.io/net-monitor:v1

meeting minutes

October 12, 2020

Attendees:

Niaz Khan (AWS)
Miloslav Trmač (Red Hat)
Jesse Butler (AWS)
Furkat Gofurov (Ericsson)
Jan Tilles (Ericsson)
Samuel Karp (AWS)
add yourself

Agenda Items:

add your topics

Notes:

meeting minutes

October 5th, 2020

Recording

Attendees:

Niaz Khan (AWS)
Samuel Karp (AWS)
Steve Lasker (Azure)
add yourself

Agenda Items:

Review feedback on https://github.com/notaryproject/requirements/pull/38
Timestamping Service Authorities

Notes:

Using TUF for root key distribution - Marina
Clarify signature validation mechanism - Niaz
Suggestions for signature verification based on package name - Niaz
Investigate whether public timestamping was considered for TUF and if there were any drawbacks identified - Marina
Focus on seom worklfows for where & how keys are acquired to enable signing and verification. Niaz to add to the key managment docs
Proposal to move 1 hour earlier to keep the existing attendees and add others that couldn’t make it. Steve to send info out on slack for others to comment.
Sounds like Friday key management meetings will merge with the Monday meetings.

September 28, 2020

Recording

Attendees:

Steve Lasker (Microsoft)
Tero Saarni (Ericsson
Derek McGowan
Marina Moore (NYU)
Trishank Karthik Kuppusamy (Datadog)
add yourself

Agenda Items:

Key Management update - Niaz
Distribution/Artifact design/working session (adding reference and collection artifact type) - Steve, Derek
add your topics

Notes:

add a collection type that wasn’t index Separate definition - not in image-spec Which manifest type they should use The stuff in image-spec used for other things. The types are defined in a generic way, but not documented as such

Separate into the artifact types Indexes suport other indexes - some registries don’t support as they don’t expect. How many levels deef should I allow? From an image client perspective

Resuing those types is a bit confusing as other clients don’t know how to handle them? Adding config to index is a good start, but we should further seperate from the image directly. Image clients - that’s the bulk of what exists today. I’d rather not touch that part of the definition and define something that’s generic. Derek - not convinced that a signature need to be an artifact. 1:many with immutable tags, but they don’t actually have tags. Special endpoints to fetch them. Should we consider endpoints that are specific to signatures More optimial for clients Give me all the signatures for this type Does it really fit in with other artifacts. Is a signature meta-data on an artifact.

Marina The order of signature discovery Do you start with the artifact, then the signature Of the 10 signatures on an artifact, how do I know to only download the 1 I care about

Derek Are attributes a way to identify which signature (generic thing) I actually want (filter upon) Is there a general way, or a specific way to get signatures Today, we thing of tags (sometimes digests) and things that refer to it

Ordering is critical to the success How do we get the digest we trust, from the tag

Different types

Artifacts
Meta-data - data on a specific object
Signatures
are tags just special types of metadata
Referneces can/must be capabile of cross repo scenarios (helm chart refences wordpress and mysql)

Clear we need an extension to the distribution api - should we add a signature api?

Separate out the searching/filtering from a single repo to across repositories

Serge - do we support signatures across repos? - do we every want to rule this out? Derek - questions on security challenges Notion of cross repo mounting exists today If a user pushes a refernece to something they don’t have access, how is that evaluated

meeting minutes

September 21, 2020

Recording

Attendees

add yourself

Agenda Items:

Proposal for generic reverse lookup #14 Open
- should we persist the config linkage
Discussion on:
- manifest generation library for non-image artifacts
- client updates for Notary v2 e2e workflow

Notes:

meeting minutes

September 14, 2020

Recording

Attendees:

Jan Tilles (Ericsson)
Samuel Karp (AWS)
Jesse Butler (AWS)
Furkat Gofurov (Ericsson)
Serge Hallyn (Cisco)

Agenda Items:

No specific items - will join for conversation
add your topics

Notes:

Progress has been on the distribution aspects which will enable signature persistance, but no specific updates to report in the nv2 prototype this week
meeting minutes

September 7, 2020 - cancelled

August 31, 2020

Recording

Attendees:

Steve Lasker (Microsoft)
Tero Saarni (Ericsson)
Marina Moore (NYU)
add yourself

Agenda Items:

TUF demo (Marina)
- Some new TUF features that address scalability concerns
- How TUF can be used with private repositories
Open Discussion on progress thus far (Steve, et all)

Notes:

meeting minutes

August 24, 2020

Recording

Attendees:

Steve Lasker (Microsoft)
Marina Moore (NYU)
Justin Cormack (Docker)
Samuel Karp (AWS)
Jesse Butler (AWS)
Miloslav Trmač (Red Hat)
add yourself

Agenda Items:

Specification and Prototype - JWT based signature update #2
Distribution API Proposal #5
add your topics

Notes:

Create an nv2 branch for prototypes, leaving main for the ultimate reference implementation
Open issues for open topics in #2 PR
Distribution Spec PR
- Index reference doesn’t explictly declare no tags - needs this for clarity
- Add a multi-arch example of signed content
meeting minutes

August 17, 2020

KubeCon EU Virtual

August 10, 2020

Video recording

Attendees:

Steve Lasker (Microsoft)
Justin Cormack (Docker)
Marina Moore (NYU)
Miloslav Trmač (Red Hat)
Varderes Barsegyan (DNAnexus)
add yourself

Agenda Items:

Review PR: Move goals and stakeholders to root readme #29 -Steve
Review PR: Add requirements doc #30 -Steve
nv2 Prototype Registry Persistence & APIs - WIP: distribution API proposals #2
add your topics

Notes:

Do we need Goals, Scenarios and Requirements? Seems the requirments can be merged into the scenarios - general agreement
For the scenarios, we have a core set of scenarios, with an additional for key managmeent. We’ll keep the key management seperate for now, enabling a streamlined working group. As they get solidified, we can merge them with the core scenarios.
Distribution Spec Signature proposals:
- Seems we have some agreement OCI Index is a better model for keeping track of depdencies, as it already tracks index to manifest. Which a signature is a link to a manifest.
- This does mean we need to continue the OCI Index supporting a config object for both persistance of the signature object, and uniquely identifying the index as a signature type. Add Index support for artifact type #25
Are signatures “special” enough to need a separate API?
- For discovery API, we briefly discussed the two paging APIs. The one consistent with the distribution tag listing, and a more generic version used on standard REST APIs. Sam provided the google API design reference.
- Do we have a signature discovery API, or a generic API for what manifests represent a given digest?
  - Provide a list of all indexes that refer to digest sha256:abc123
  - Provide a list of all indexes that refer to digest sha256:abc123 that has an artifact type of application/vnd.cncf.notary.config.v2+jwt
- Agreed to defer this to online conversation
- For signature upload in relation to role based access: rather than have a separate API for signature linking, that wouldn’t scale to other artifact types, should we use the standard push/upload APIs and outline role check should be done enabling a scalable and consistent model for other artifact types?
Steve to finish documenting WIP: distribution API proposals #2, incorporating feedback
Please provide some eyes on the JWT encoding staged PR

July 31, 2020

Recording

Attendees:

Niaz Khan (AWS)
Steve Lasker (Microsoft)
Marco Franssen (Philips - Research)
Marina Moore (NYU)

Agenda Items:

Multiple Root Keys
Key Revocation

Notes:

Key sharing service serves the purpose of multi-registry world.
- it allows a company to define what they trust
Registry clients connect to key sharing service to fetch trusted roots
- To prevent usability issues a client should be able to connect to a single key sharing service
Key sharing service can be used to redirect to other key sharing services or give an overview of the trusted keys
- What are potential threads for the key sharing service?
- How can we protect against these threads?
- The key sharing service should also be able to run as an offline airgapped service. This allows offline/airgapped solutions to rely on this airgapped service.
Should the keysharing be embedded in the registry?
How does key revocation propagate to clients via key sharing service?
meeting minutes

July 27, 2020

Recording

Note: Meeting will be 7am Pacific time

Attendees:

Steve Lasker (Microsoft)
Shiwei Zhang (Microsoft)
Miloslav Trmač
add yourself

Agenda Items:

nv2 signing prototype Shiwei / Steve
add your topics

Notes:

Outline the multiple signature scenario better - identifying how the references could be used
Questions on scopying and support of TUF metadata
Ouline what’s in prototype phase 1, vs. future prototypes - like TUF metadata. Ralph volunteered to help - and it’s now written in history
meeting minutes

July 24, 2020

Recording

Attendees:

Niaz Khan (AWS)
Marco Franssen (Philips - Research)
Justin Cappos (NYU)
Marina Moore (NYU)

Agenda Items:

Finalize Pull Request PR

Notes:

Revisions for scenarios doc:
- Define addtional personas for deployment roles and registry operators
- Add diagrams to clarify steps in signing, uploading to registry, and deploying containers
- Add diagrams for key rotation
- Clarify how air-gapped regions can manage trust store
Root rotation now involves a third component. Does this introduce additional risk?
- Justin to clarify risk for discussion at next week’s meeting.

July 20, 2020

Recording

Attendees:

Steve Lasker (Microsoft)
Marina Moore (NYU)
Justin Cappos (NYU)
Miloslav Trmač (Red Hat)
Trishank Karthik Kuppusamy (Datadog)
Donald Stufft (Datadog)
Samuel Karp (AWS)
Jesse Butler (AWS)
Niaz Khan (AWS)
add yourself

Agenda Items:

Key management working group discussion PR (Niaz)

Notes:

Should we support CAs?
- May be optional, but shouldn’t be required. If needed, an extensibility option.
- Not clear there are benefits for CA keys, and Cappos hasn’t seen much demand.

July 17, 2020

Recording

Attendees:

Niaz Khan (AWS)
Marco Franssen (Philips Research)
Justin Cormack (Docker)
Justin Cappos (NYU)
Trishank Karthik Kuppusamy (Datadog)
add yourself

Agenda Items:

add your topics

Notes:

Some open questions
- How to sync certificates to be known to different notary instances? (public vs private company internal)
  - Airgapped.
  - Pulling from different registries at runtime platforms
- How to enable self managed portal for bigger organizations?
  - admins can manage creation of new targets
  - team can manage delegations themself for their targets
- How would a CI job retrieve it’s delegation and cleanup afterwards to sign images?
  - Auto expire after 10 minutes (lifetime of CI job)
  - Auto register this CI delegation on the given target
    - Does an ACME like challenge work here?
Review draft of use cases for key management scenarios
- Justin and Trishank to do this
- Raised some potential issues on role/metadata files vs signatures directly on manifests/indices, and scalability of revocation lists vs explicit metadata on keys
- Niaz interested in use cases such as different roots of trust in a registry: e.g., company vs individual developers
- Niaz to add in motivation on why steps are being taken.

July 13, 2020

Attendees:

Justin Cormack (Docker)
Steve Lasker (Microsoft)
add yourself

Agenda Items:

Niaz wanted more time to incorporate feedback. Watch for an invite for this friday for key signing scenarios.
no agenda, agreed to defer to next week.
add your topics

Notes:

meeting minutes

July 10, 2020

Attendees:

Niaz Khan (AWS)
Steve Lasker (Microsoft)
Marco Franssen (Philips Research)
Ian Kaneshiro (Ctrl Cmd)
add yourself

Agenda Items:

Scope of key management scenarios
Dates
- 7/10 Identify use cases
- 7/17 Detail out all use cases
- 7/24 Review draft requirements
- 7/31 Finalize requirements
Review pull request https://github.com/notaryproject/requirements/pull/27

Notes:

Hybrid scenario for root key in HSM, delegate key on local machine.
Add in details for how hosts are configured.
Philips solution for managing Notary v1 keys. https://github.com/philips-labs/dct-notary-admin/tree/develop/docs
meeting minutes

July 6, 2020

Recording

Attendees:

Steve Lasker (Microsoft)
Trishank K Kuppusamy (Datadog)
Justin Cormack (Docker)
Samuel Karp (AWS)
Niaz Khan (AWS)
Omar Paul (AWS)
Tero Saarni (Ericsson)

Agenda Items:

Preliminary sharing of experience with Signy on Notary v1
- What is CNAB?
- What is CNAB Security?
- MVP to sign bundles
- Extending MVP to add SBOM
- Example minimal SBOM: machines can only add hashes for images in bundles, but nothing else
- Signy: the reference implementation for CNAB-Sec
- Lesson #1: reusing keys
- Push timestamp and snapshot to server/signer
- As of today morning, Philips dct-notary-admin is also doing the same
- Reuse root and targets across bundles/repos
- Need to revisit idea why Notary needs a separate metadata repo per image/bundle/etc
- Lesson #2: using the power of delegations
- What are delegations?
- Using delegations to safely include SBOM metadata
- notary-dct-admin also would like to use the delegations to decentralize how developers use their keys
- Demo
Lessons from notary-dct-admin
- Interested in Notary v2
- Working with extending Notary v1, like Signy, in the meantime
- Agnostic storage and key backends
- One-click key revocation
- Looking for funding (can CNCF help here?)
EU+Asia friendly meeting time?
- Harbor, Philips, etc are interested
- We should include them
add your topics

Notes:

Radu and Trishank to write an issue about lessons learned
meeting minutes

June 29, 2020

Recording

Attendees:

Niaz Khan (AWS)
Steve Lasker (Microsoft)
Samuel Karp (AWS)
Tero Saarni (Ericsson)
Serge Hallyn (Cisco)
add yourself

Agenda Items:

A sketch and process for how and where SMEs can engage in an exploratory prototype (Steve)
Ephemeral clients as a design requirement. (Justin Cormack)
add your topics

Notes:

meeting minutes

June 22, 2020

Recording

Attendees:

Niaz Khan (AWS)
Steve Lasker (Microsoft)
Marina Moore (NYU)
Justin Cappos (NYU)
Donald Stufft (Datadog)
Trishank Karthik Kuppusamy (Datadog)
Tero Saarni (Ericsson)
add yourself

Agenda Items:

Metadata overhead comparison (Marina)
Scheduling Key Management meeting https://doodle.com/poll/ziiqg66hnbnmhygw
Pull request for Key Management Scenarios (Niaz)
add your topics

Notes:

meeting minutes

June 15, 2020

Recording

Attendees:

Steve Lasker (Microsoft)
Marina Moore (TUF)
Justin Cappos (TUF)
Trishank Karthik Kuppusamy (Datadog)
Niaz Khan (AWS)
Radu Matei (Microsoft)
Tero Saarni (Ericsson)
Evan Cordell (Red Hat)
Samuel Karp (AWS)
Derek McGowan
Aaron Lynch (AWS)
Donald Stufft (Datadog)
add yourself

Agenda Items:

Notary design scenarios and TUF
- Where do we go from here?
add your topics

Notes:

Registry/Repo RBAC -Storage - Write up a constraint/scenario such that signatures/metadata are stored alongside image data, without the need for a separate service endpoint. (Steve)
Need key management scenarios written up. Marina offered to make a PR with the initial key management scenarios.
meeting minutes

June 8, 2020

Recording

Attendees:

Steve Lasker (Microsoft)
Niaz Khan (AWS)
Trishank Karthik Kuppusamy (Datadog)
Justin Cappos (NYU)
Serge Hallyn (Cisco)
Tero Saarni (Ericsson)
Miloslav Trmač (Red Hat)
Tue Tran
add yourself

Agenda Items:

Target Scenarios for nv2 prototype
Added signature verification lookup design pr#22 copied from google doc: Notary v2 - Verification Persistence by Reference
- Mitr - good to have a requiment to not require changing digest references
- Cappos - non goals - protection from attack if a registry is compromised.
Cappos (ran out of time; pushed to next week)
- Discussion with Samuel Karp
- Security issue
- Performance will come next week
add your topics

Notes:

meeting minutes

June 1, 2020

Recording

Attendees:

Steve Lasker (Microsoft)
Aaron Lynch (AWS)
Samuel Karp (AWS)
add yourself

Agenda Items:

Target Scenarios for nv2 prototype
Added signature verification lookup design pr#22 copied from google doc: Notary v2 - Verification Persistence by Reference
add your topics

Notes:

meeting minutes

May 25, 2020

Meeting cancelled per US Memorial Day Holiday We’ll reconvene next Monday, June 1st

May 18, 2020

Attendees:

Steve Lasker (Microsoft)
Tero Saarni (Ericsson)
Radu Matei (Microsoft)
Serge Hallyn (Cisco)
Stuart Hayton (IBM)
Samuel Karp (AWS)
Evan Cordell (Red Hat)
Niaz Khan (AWS)
Marina Moore (NYU)
add yourself

Agenda Items:

TUF signatures
add your topics

Notes:

meeting minutes

May 4, 2020

Attendees:

Steve Lasker (Microsoft)
Marina Moore (NYU)
Trishank Karthik Kuppusamy (Datadog)
Samuel Karp (AWS)
Serge Hallyn (Cisco, lurking)
add yourself

Agenda Items:

Cappos, Moore, Kuppusamy: Thoughts on Notary-v2 design proposals

Notes:

Should a signature couple a tag and a digest to say that combination is “signed” and verifed at a given time?
We haven’t yet written down a “requirement” that digests and/or tags can’t change as the result of signing an artifact. Is that a requirement?
Attacker goals in the threat model

May 4, 2020 - nv2

Attendees:

Steve Lasker (Microsoft)
Samuel Karp (AWS)
Marina Moore (NYU)
Trishank Karthik Kuppusamy (Datadog)
add yourself

Agenda Items:

Where do signatures go?
Signatures in OCI
Notary v2 - Verification Persistence by Reference
Deisgn Options
add your topics

Notes:

Cappos, Moore, Kuppusamy - some feedback on the Deisgn Options
- Option 3, does the entire SBOM have to be entireley downloaded?
- Does the SBOM need to be signed as well
- sam - sign an sbom of the sbom
- What does the client request, an image, or a tag?
  - the client requests a digest or a tag
- Discussion of option 4 having separate uploads of signed content
- Discussion of whether a digest can or shouldn’t have to change
  - Can a naming convention be used?
  - Joey - when a signature is pushed, an entry is pushed as the orignal manifest, with a new api that links manifests and declaration.
- Vincent - Reminder for the need to track separate ACLs
- Cappos - can you trust a registry?
- Joey - can pushes of linkages between docuemnts be identifiable for walking back compromises
- Cormack - can we build a secuirty solution without reverse linkages?
Additional references:
- OCI Distribution-spec ext discussion
meeting minutes

April 27, 2020 - nv2

Recording

Attendees:

Steve Lasker (Microsoft)
add yourself

Agenda Items:

add your topics

Notes:

Justin Cormack - Doc for a minimalisitc implementation to get started. Tuf with a separate doc format for fitting in a registry to see where it goes.
meeting minutes

April 27, 2020

Attendees:

Steve Lasker (Microsoft)
Aaron Lynch
Niaz Khan (AWS)
add yourself

Agenda Items:

add your topics

Notes:

meeting minutes

April 22, 2020 - nv2 breakout

Attendees:

Steve Lasker (Microsoft)
Samuel Karp (AWS)
add yourself

Agenda Items:

Identify some goals of the experience.
Sketch out an experience for SMEs to engage within their areas.
- Learn what’s hard that needs more investments
- Learn what’s easy, we can just do now
Repos for iteration:
- https://github.com/notaryproject/nv2 - Notary v2 Client we’ll experiment with
- https://github.com/notaryproject/distribution - For any potential changes we’d want to push back to the distribution-spec.
Housekeeping
- what language will we use?
  - Golang
- what are the apis/ux we’ll focus on?
- what are the extension models we need to support for the nv2 client
- What are the registry extensions do we need?
- maintainers
MVP
1. Sign an artifact
2. Push the artifact and signature to a registry
3. Pull an artifact from a registry, validating it’s signature
Needs
1. Concrete representations for signatures
2. API changes required on distribution, if any
Prototyping Order
1. Sign & Push a signature to a registry
  - Manifest is in the registry
  - Persistence - how do we represent a signature in the registry?
2. Pull an artifact from the registry, validating it
Misc discussion
- How to manage ACLs on signatures and artifacts?
- VBatts - should be able to sign layers
- Justin - should we be able to sign artifacts not owned
  - Steve - customers want to sign content for different environments, which means they are signing someone elsese content
  - in-repo signatures as a first model
- Focusing on detached signatures
  - extension proposal #111 (discussion https://hackmd.io/Ljkrt0LORmeVznREeGOWuQ?edit)
  - Push an artifact, then push another manifest that includes a signature for that artifact. It could support mulitple signatures.
  - Steve - How can we support immutable manifests so users don’t have to pull/push and the registry needs to cope with updates?
  - Sajay - the concept of a signed manifest that points to the content and the signature.
    - Tags can be updated, but the content digest doesn’t get updated.
  - Derek - how to reference signature collections, as opposed to tag listing.
  - VBatts - can unordered list be pushed, so the collection doesn’t need to be signed?
  - Need to account for deleting signatures when the artifacts are deleted.
  - Justin - additional signatures can be pushed to the registry, as a signature manifet.
  - Can we push individual index objects, each with a separate signature so we don’t have to update a single signature index?
    - There’s no existing reverse lookup for the indexes that represent a manifest
  - Sajay/Justin - could we morph Notary v1 metadata with a Notary v2 model to have tags updated with new signatures. Client can infer a naming scheme with different properites.
  - Steve - can we say Notary v2 doesn’t store different pointers for signed and unsigned content for the same tag?
ToDo:
- Steve to add a comment to the distribution fork readme.md to identify it’s for collaboration on changes we might propose to the distribution spec and eventually merge back to docker/distribution.
add your topics

Notes:

meeting minutes

April 20, 2020 - Monday call

Recording

Attendees:

Steve Lasker (Microsoft)
Stuart Hayton (IBM)
Aaron Lynch (AWS)
Miloslav Trmač (Red Hat)
Niaz Khan (AWS)
Radu Matei (Microsoft)
Samuel Karp (AWS)
Tue Tran (AWS)
Derek McGowan (Docker)
add yourself

Agenda Items:

Scenarios Update
Prototype
add your topics

Notes:

Scenarios Update
Prototype
Aaron - what’s the value of the signature?
- Discussion of signature and post validation verificaiton using TUF
Justin Cappos
- Discussion of signatures being the foucs, vs. verification, which had been the trusted “annotation”. Focus on the result, that the document wasn’t tampered with.
Niaz
- Layered approach, which could include additional meta-data
- What’s a core, vs. extensibility requirement?
  - eg: Do some signatures can about names, while others may not
meeting minutes

April 20, 2020 - nv2 experiment

Attendees:

Steve Lasker (Microsoft)
Justin Cormack (Docker)
Omar Paul (AWS)
Stuart Hayton (IBM)
Aaron Lynch (AWS)
add yourself

Agenda Items:

add your topics

Notes:

Signing vs. Content Verifcation
Multiple phases
1. What does a signed document in a registry look like
2. Prototype this in the OSS registry
3. Write a client that can push/pull signatures
4. Write a client that can valiate signatures
5. Build a more complex client, like TUF, that would layer atop the above signatures and validation
First we fork docker/distribution
- Add root signature api
Add an nv2 client to push/pull/sign content
Then, we add a tuf client that uses the above interfaces
- Tuf client takes tuf repository to a registry version, then converts it back
Key Managemnet
- APIs for external key management solution
- Solution for the 98% of others
Next nv2 call
- Justin Cormack - Wednesday or Friday 9am or 10am
- Derek - Wednesday 9 or 10
- VBatts
- Sam - Wednesday 10
- Sajay
meeting minutes

April 13, 2020

Recording

Attendees:

Aaron Lynch
Steve Lasker (Microsoft)
Samuel Karp (AWS)
Niaz Khan (AWS)
Evan Cordell (Red Hat)
Serge Hallyn (Cisco)

Agenda Items:

Working group status
- Sceanrios Feedback
  - Push/pull between signing and tuf evaluation PR# 15
  - Justin - if we over scope scenarios, we narrow the conversation
    - Focus on the goals, leaving as much as possible about the mechnisms out. ex: have to have puncture resitant tires on an ambulance removes the option to have helicopters
  - Niaz - can we assure we’re capturing the notes in the PRs.
- Threat Model Update
  - Niaz - until we have more of a design in place, it’s hard to do a threat model analysis. At the high-level we have the threats we want to capture. Some conversations around key management.
  - “What does signing attest to”, for example.
  - Discussion about splitting up the threat model requirements, vs. an actual threat model of a design.
  - Key managment spearate from a threat model design.
UX flow
- We’ll start to sketch out an experience for iterative work. There’s nothing concerete about the sketch, rather an experience to learn from, enabling folks to engage with their expertise.
Housekeeping
- Niaz suggested we see if we can get a different time slot, which he’ll help coordinate for brekout meetings. We’ll chat on the Notary v2 slack channel for everyones visibility.

Notes:

April 6, 2020

Attendees:

Steve Lasker (Microsoft)
Aaron Lynch (AWS)
Samuel Karp (AWS)
Niaz Khan (AWS)
Tue Tran (AWS)
Miloslav Trmač (Red Hat)
Vibhav Bobade (Red Hat)
add yourself

Agenda Items:

Working group status
- Scenarios
- Key Management / Threat Model
- Signature Persistance
- UX

Notes:

Discussion for how to represetnt a TUF concept of a collection
What is the extent of design/constraints are we hitting? Is the existing OCI Index/Manifest design enough?
We’ve been working with the assumption the existing OCI spec meets most of the capabilities, with some tweaks. But, that may not be the case.
Threat model team to focus on more documentation of the proposal and discussion.
Hoping to get more progress, as is reasonable, within the next week
Ask to wrap up the current PR for scenarios so we have a common doc to reference. We can and will likely iterate on additions, but lets get a Scenarios PR merged.
meeting minutes

March 30, 2020

Attendees:

Steve Lasker (Microsoft)
Joey Schorr (Red Hat)
Josh Dolitsky (Blood Orange)
Peter Engelbert (Blood Orange)
Miloslav Trmač (Red Hat)
Rita Zhang (Microsoft)
Richard Nguyen (AWS)
Samuel Karp (AWS)
Matthew Russo (AWS)
Tue Tran (AWS)
Shubhra Deshpande (AWS)
Vincent Batts
Adrian Mouat (Container Solutions)
Aaron Lynch (AWS)
Radu Matei (Microsoft)
Ram Chinchani (Cisco)

Agenda Items & Notes

9:00am – 9:30 Artifacts update
- Status of the spec
- IANA mediaType registration updates
- Josh - how many types would need anything more than the generic ones?
  - Steve - likely not many. But, if they do, they can
- Joey - We need to make sure the proposal states that handling of downloaded layers/blobs is artifact specific. As well, if we are mixing different kinds of artifacts, it should be done via an index, not using different layers (IMO)
- Repo: https://github.com/opencontainers/artifacts
9:30-10:00: Getting the Distribution Spec to a 1.0
- A set of proposals, such as the extension proposal #111 that could get incorporated into the 1.0 spec.
- Hanging extensions off a repo enables ACL (Access Control Lists) to be enforced on the extnesion, in relation to the artifact.
- Minor details - like the Readme.md need updates
- Clarifications that are flushing out from the conformance testing.
- Josh - Spec Language Updates
- VBatts - Would like to get an RC2 out
10:00-10:30: Supporting the Secure Supply Chain efforts
- How OCI, Artifacts & Notary can support the Software Supply Chain efforts with SBoM, GPL Source and other content, stored in a registry, signed with Notary v2.
10:30-11:00 Notary v2
- Derek - Signatures in OCI Distribtuions
  - Fit into the existing OCI spec
  - Planning on having the extension design integrated to allow for signatures
- Discussion of signing collections, querying a collection of signatures
- Discussion of offline verification of signatures using snapshots
  - good conversation for the breakout groups

Threat model meeting 27 March 2020

Attendees:

Justin Cormack
Justin Cappos
Niaz Khan
Marina Moore
Samuel Karp
tuetran
lahiru

Agenda Items:

where are we with threat model?

Notes:

TODO: remove from scenarios doc any design pieces
TODO: improve wording on thread model: forward looking crypto agility
roles: operator, producer consumer
motivation vs what is wrong
do we have to trust the registry?
minimal possible trust.
how does user get trust of publisher. If user knows the key registry doesnt neeed trust.
naming vs location. third party vs first party.
registry A deletes software where you have in B. How can you continue to trust.
model of who the actors are and what they are trying to achieve.
TODO: list of roles (the length of the threat model) and basic use cases.
Which roles are providing signatures?
Information about them.
Signing collections is impossible.
discussion about properties of registries - privacy needs.
Niaz: key administrator role. Add as a TAP for TUF?

March 23, 2020

Attendees:

Steve Lasker (Microsoft)
Miloslav Trmač (Red Hat)
Dan Lorenc
Samuel Karp (AWS)
Carmen Puccio (AWS)
Trishank Karthik Kuppusamy (Datadog)
Marina Moore
add yourself

Agenda Items:

A quick check-in for folks
Breakout Updates
add your topics

Notes:

NOTE: we appreciate some may be coping with, assisting others at this time. While others are looking for something creative to do with their time. We’ll continue to the weekly meetings, with breakouts where possible. We will NOT make any fina/final decions as we recognize that some may not be able to engage right now. We expect things to get worse before they get better, so we’ll continue to adjust. If you’re leading a breakout, and need to step back, please just ask for some help to take the lead. We’re a diverse group of people that are here becuase we believe in community, which is made of people.- meeting minutes
Some were confused about the start time. Steve to update the heading of these notes. Please see the cncf calendar as Amye has been awesome to keep these updated.
Breakout Updates
Justin-Hoping to get a threat model this week
- #notary-v2-oci slack channel created
Steve - Discussion on status of scenarios. If we can get :eyes: on #15 we can wrap-up a baseline
- Discussion of the mirroring PR, looking great. A minor clarification on the verification step so we can also merge.
Key Management - possibly create another slack channel
- Trishank to send a draft of a key management HackMD
Please put breakout notes here, with a mid-week update if needed - AJust add another ## heading
Some teams may split out to another slack channel, with a link provided here for others to engage.
A bit of a concern about too many slack channels. If we do, lets try to keep them focused and not force folks to montior too many slacks.
- We’ll update here weekly for those that want to hear, but don’t have time to egnage
Initial Design Ideas
- should we move these to an issue, or another location?
- Samuel - the requriements repo is a working location
  - we’ll continue it here, as issues doesn’t have good editing/comments
  - Justin spoke to the hackmd folks
  - VBatts - would be great if we could somehow integrate hackmd with github
  - At this point we’ll keep things where they are. As we get further along in design, or we may merge this in as it evolves.

March 16, 2020

Attendees:

Steve Lasker (Microsoft)
Justin Cormack (Docker)
Miloslav Trmač (Red Hat)
Niaz Khan (AWS)
Tue Tran (AWS)
Samuel Karp (AWS)
Marina Moore (NYU)
Trishank Karthik Kuppusamy (Datadog)
Evan Cordell (Red Hat)
Dave Trudgian (Sylabs)
Justin Cappos (NYU)
Aaron Lynch (AWS)
Ian Kaneshiro (Sylabs)
Dan Lorenc (Google)
Dave Billing (Cisco)
Vibhav Bobade (Red Hat)

Agenda Items:

Breakout Recap
- Justin - Signature Storage conversations with Vincent & Derek. A writeup will be done for next week
- Steve - Scenarios have been staged for PR feedback.
  - Readme Link Fixup
  - Scenario updates, incorporating scenarios from @JustinCappos
Key Management needs a separate focus from Threat Model
- Discussion of getting more details on the threat models before we focus on details of key managment
Breakout teams will split off for discussions
- Please use this Hackmd.io doc for those working at different times
- Post meeting times for those that can attend, and subsequent recordings
  - Threat model meeting: https://calendar.google.com/event?action=TEMPLATE&tmeid=NXUzbXZmZzZhY2RwbmZwc3VsbDBnbTFtcmwganVzdGluY2FwcG9zQG0&tmsrc=justincappos%40gmail.com
Radu did a Helm 3 w/Notary 1 prototype: https://github.com/helm/helm/pull/6282
- Uses signatures, pushed to OCI Artifact supported registries, pushed with ORAS

Notes:

meeting minutes

March 9, 2020

Attendees:

Aaron Lynch (AWS)
Niaz Khan (AWS)
Justin Cormack (Docker)
Jon Johnson (Google)
Dave Billing (Cisco)
Marina Moore (NYU)
Joshua Lock (VMware)
Evan Cordell (Red Hat)
Justin Cappos (NYU)
Radu Matei (Microsoft)
Serge Hallyn (Cisco)
Miloslav Trmač (Red Hat)
Daniel Jiang (VMware)
Ram Chinchani (Cisco)

Agenda Items:

Breakout groups for Scenarios+UX and Key management+Threat model

Notes:

KubeCon meeting (Steve)
- Witht the postponement of KubeCon, we moved to an online meeting. I will reschedule to start at 8am Pacific time, to account for Europe folks.
- I’ll have other meetings for Artifacts and possibly the Pub/Sub work Joey has been working on that will happen from 10am to possibly noon. With the KubeCon plan confirmed, I’ll get these meetings finalized as well.
Breakout groups
- Use Cases & UX (api/interaction model)
  - (Steve, Omar, Marina, Aaron, Ram, Tue)
- Threat Model & Key Management
  - (JustinCr, Justin Cappos, Niaz, Evan, Dave B, Miloslav?, Serge. Tue)
- Signature Storage within the OCI spec
  - (JustinCr, Vincent, Derek, Sam, Jon, Daniel J, Serge, Tue)
- Reference Implementation
  - Docker Distribution?
  - How does it interact with k8s, OPA and SBoMs
  - Zot very interested in implementing asap
Keep the exising Monday meeting for status sync. Reduce to 30 minutes. Will move to the later hour to free up the first 30 minutes for groups to meet prior.
Naming: Will leave open for now, pending the threat model discussions. (serge asks - where will that discussion happen?)
Timeline
- Going to hold to our original April timeline for an initial design.
  - use the 2 hour March 30 meeting for a summary reporting of the groups.
  - KubeCon EU July Notary v2 First Proposal
  - KubeCon US November 17 a working reference implementation.
How do we think about Notary v2 and registries? Does success of Notary v2 end with a registry conformance/implemenation? Or, is it assumed Notary v2 stands alone outside registries?
- The ability to pull an artifact from a registry, validate it outside of a registry is part of our success.
- End-to-end verification implies signing/verification outside registries; OTOH smooth usage ~requires registries natively supporting transport of signed data
meeting minutes

March 2, 2020

Attendees:

Steve Lasker
Stuart Hayton (IBM)
Brandon Lum (IBM)
Radu Matei (Microsoft)
Niaz Khan (AWS)
Joshua Lock (VMware)
Marina Moore (NYU)
Samuel Karp (AWS)
Dave Billing (Cisco)

Agenda Items:

Last Weeks On Site Meeting Recap - Steve
SBoM Integration - Steve
Divide & Conquer - Steve/Justin
add your topics

Notes:

With the focused conversation last week, we didn’t have much new content. We did a quick cover of the naming and CNAB notes from last week. See below.
- Definition & Terms
SBoM conversations to verify alignmnet that there is a doc that would be put in a registry, which is then signed.
Divide & Conquer to start focused design meetings. Specific groups TBD.
Look into setting up irq on the slack channel - Serge
Notary Project Requirements for the current state of content, with Justin’s Google Doc here

February 24, 2020

Steve Lasker (Microsoft)
Samuel Karp (AWS)
Tue Tran (AWS)
Justin Cormack (Docker)
Aaron Lynch (AWS)
Niaz Khan (AWS)
Omar Paul (AWS)
Sajay Antony (Microsoft)
Radu Matei (Microsoft)
Trishank Karthik Kuppusamy (Datadog)
Jon Johnson (Google)
Marina Moore (NYU/TUF)
add yourself

Agenda Items:

What’s in a name?
Review a quick doc on image/registry mirroring
Notary v2 and CNAB
Timeline of what is possible by Kubecon EU 2020?

Notes

Justin/Steve/Sam/Omar: Mirroring is not as straightforward in container registries as in package repos. An image is accessed with a location as core part of the image-therefore signing the image also signs where its stored/retrieved, therefore you today sign the image and where it comes from.
“Sam Q: What does a signature tell you?" Aaron - Gives you a hash over a bag of bits, gives you the publishers identity and lets you validate the publisher at a later time. Sam - specifically, lets you validate a key and only tells you the publisher is trusted and the object is what was signed, not anything inherent about the content outside of what a publisher says it is. Steve - tells me that this content is trusted because I trust the publisher that signed it. The name of that signed object should also be trusted. Justin - I have to be able to know that I signed something with a name, and if I access that later with a name, I should be able to trust that without checking the content hash again.
Should we let people change a name:tag and keep the signature valid - If we don’t allow this, existing container workflows will break.
Sajay - We need to be able to describe the discoverability and the signature validation seperately.
- Extending Index to support storing signatures is one option.
Trishank - We can support different models of trust at the same time
- Option 1: trust Docker to give me the keys for an image
- Option 2: trust Docker only to give me the signatures and the images, and I will pin the keys
- Options need not be mutually exclusive: there is no reason why we cannot support both weak and strong signing models; it should be flexible
- Appears that we need mechanisms for transparent key distribution and revocation, as well as pinning your own keys, as well as ways to somehow order keys using some well-defined criteria for trust
What are we signing? - Justin signing the descriptor is the correct thing, and if the exact same content is pushed, then pulled and pushed into a second location, and the content hash changes - thats a tooling issue. Radu - insert comment here
Min. bar for Notary v2 of OCI needs to be Distribution Spec v1 - As a carrot/forcing function.
How much are we willing to change?
- We’re changing the docker content trust workflow. Are we willing to change the workflows, such as other package managers like npm, rpm, nuget?
Diverging from TUF
- Justin: So far, not seeing a use-case for using the snapshot role to sign a collection of images, since it’s ok to change the version/tag and not have the signature be invalid.
- Marina: The snapshot role does prevent against rollback attacks of images.
- Trishank: Also, how does this affect security guarantees the TUF project designed for Docker Hub hosting images on semi-trusted mirrors, where the mirrors may be able to switch images?

Notary v1

The entire path is signed docker pull org.exmple.com/team-a/mydb:1.0

Keeping the name, different path

docker pull org.exmple.com/team-a/mydb:1.0 docker pull org.exmple.com/staging/mydb:1.0 docker pull org.exmple.com/prod/mydb:1.0

Keeping the name, different registries

docker pull org-dev.exmple.com/team-a/mydb:1.0 docker pull org-staging.exmple.com/team-a/mydb:1.0 docker pull org-prod.exmple.com/team-a/mydb:1.0

Changing the tag, representing the env

docker pull org.exmple.com/team-a/mydb:1.0 docker pull org.exmple.com/team-a/mydb:1.0-staging docker pull org.exmple.com/team-a/mydb:1.0-prod

Tagging References

Docker Tagging: Best practices for tagging and versioning docker images

Comments
- Trishank: I agree with the docker best practices for tagging and versioning docker images
- Trishank: We cannot depend on the registry not changing the contents of the tags (unless you couple with something like immutable history with Transparent Logs, but that is a whole another can of worms by itself)
- Jon: Definitely agree it seems like signing and tag verification can be solved separately… the go modules transparent log work seems to map pretty well to registry tags

Proposal to implement the above in Notary v2

Notary v2 will support this use case

com.docker.justin:foo <- canonical image name
justin:foo <- Docker Hub image name
registry.example.net/mirror/image:bar <- diff. location where this content is mirrored Example commands
docker pull justin:foo –from registry.example.net/mirror/image:bar
docker pull Sajay TBD
docker build –tag justin:foo –canonical-name com.docker.justin:foo –sign $KEY_ID

CNAB doc notes

Lets see if Notary v2 does not explicitly block what CNAB already does with TUF and Notary v1. Support TUF 1.0 delegation.
Radu and Trishank will file an issue on the Notary v2 requirements GitHub repository about exactly what we need. A lot of this touches hairy key management issues we will ultimately need to address anyway.

ToDos

Steve to merge in Justin Cappos scenarios
Sam to capture the naming conversation and next steps

By Kubecon EU, achieve what?

Sam: What are our goals and what are not. Do we know what we’re signing, and what does this mean for OCI?
Justin: How modular is this, what are the basic use cases, and what that usability is
Steve: Define scope of Notary v2, so we can share with others as well (SBoM, etc.) can understand what we will and won’t do. What is needed from the OCI spec?
Sajay: A containerd plugin PoC that shows what Notary v2 can be?
Niaz: Understand key management requirements, need to make sure its not super easy to do this - ensure we keep some friction here. [Action] Justin (Docker), Niaz (AWS) will start to meet up on this, with Steve (Msft) bringing someone onboard in the coming weeks.

February 18, 2020

Attendees:

Steve Lasker (Microsoft)
Samuel Karp (AWS)
Tue Tran (AWS)
Lahiru (AWS)
Justin Cormack (Docker)
Aaron Lynch (AWS)
Niaz Khan (AWS)
add yourself

Agenda Items:

Review Scenarios
Review Definitions & Terms
Design discussions
- What metadata should we include, and what should we defer to other SBOM type projects?
grpc key store client feature
Singularity related background
TUF Delegations
add your topics

Notes

Scenarios
- JustinCappos Another scneario: what happens when things go wrong, and the keys are compromised? Or, what to do when a specific key was compromised.
- Steve - are these the revoking scenarios?
- (Niaz) - we don’t revoke keys as much as we revoke trust
- JustinCappos - If we have a man in the middle attack -
  - It matters what was signed with the key, and when. But, how do you go from the bad state, back to a good state.
  - Should also incorporate offline/copied artifacts that were copied to another registry.
- How do we want to scope in/out various topics to the scenarios doc.
  - For instance, key managmenet.
  - Scenarios should avoid the specific technology, such as HSM. Rather we refer to keys, regardless of how the key is “managed”.
- New Scenarios
  - (Justin) #1 doesn’t mention how the developer would validate the base image is valid
  - (Niaz) How to accont for the scenario where the image is validated, then deployed. Between validation and deploy, how do verify the artifact wasn’t compromised. Basically, once the image has been unpacked, how do we validate it.
  - Should the hosting environemt be in-scope?
    - (JustinCormack) Or, is this more about specific artifact type validations?
  - (Raja) Should be careful to not design something that belongs in the artifact specific runtime.
- For the artifact naming/moving, the existing scenarios aren’t crisp enough. Might cover the local mirroring for IoT/OnPrem or workflow from dev-prod.
  - What are the minimum set of scenarios, vs. stretch goals?
  - What are we signing? What does signing an artifact mean?
Threat Models
- Agreement to create a separate threat-model.md document. (JustinCormack) - merged
- Cappos - how to identify how the thing was compromised? It’s not just a scanning question.
- We should valiate the integrity, not enforce a policy
- (JustinCormack) - how do we account for names being verifiable? If I can’t verify by name, I can’t trust it, and will revert to @sha256 digest references
Merging
- Agreed to merge the existing docuemnts (scenarios, def & terms, and threatmodel), and iterate upon them.
validation logic
- What are we validating?
  - Key?
  - Name?
  - Version?
  - Entity?
- What does a validation look like?
  - Produced with a key that I trust
  - Producted by any key (it was signed and traceable)
  - The signature has an identity (Microsoft vs. micosoft)
  - When was it signed
  - Does the signature expire
Open Topics
- Naming & Signing
- Validate before run
- TOFU vs. Explicit
Definitions & Terms
- _
Key Management
- Where keys are stored aren’t completly in scope.
- The usability for how keys are used are in scope for the usability goals of notary v2.
Design Discussions
- Where to store the signature info?
Parking Lot
- Key Management
- Heirarchicy of keys
- grpc key store client feature - will defer to a later conversation.
meeting minutes docker pull org.exmple.com/team-a/mydb:1.0 docker pull org.exmple.com/prod/mydb:1.0 docker pull org.exmple.com/prod/gibbly:v1dsdf0 –name mydb:1.0

February 3, 2020

Attendees:

Steve Lasker
Justin Cormack
Stuart Hayton (IBM/ICCR)
Jim Flanagan (AWS)
Jack Baines (IBM/ICCR)
Tue Tran (AWS)
Samuel Karp (AWS)
Niaz Khan (AWS)
Brandon Lum (IBM/Research)
Omar Paul (AWS)
Joey Schorr (Red Hat)
Evan Cordell (Red Hat)
Miloslav Trmač (Red Hat)
Ian Kaneshiro (Sylabs)
add yourself

Agenda Items:

Dividing & Conquering with a Separation of Concerns - How Notary v2, SBOM, Policy Managmenet and Orchestrators can take on specific areas - (Steve)
What We Sign (Justin) https://docs.google.com/document/d/1lffOYCDXBoxRumQre32yv1jUN2NfOkWugoDEJ_2DdEk/edit
add your topics

Notes:

Overview of how to think of Notary signatures, versioning, etc: Dividing & Conquering with a Separation of Concerns
Mitr: Concerned about interoperability.
Justin: Package managers tend to sign a smaller set of metadata. If they uniquely sign the mysql:3.16 image, is that the minimal use case?
Discussion of what’s signed. The manifest, or the artifact:tag name.
Signature Lifetime: Should signatures have a lifetime?
meeting minutes

January 27, 2020

Attendees:

Steve Lasker (Microsoft)
Dave Trudgian (Sylabs)
Stuart Hayton (IBM/ICCR)
Ian Kaneshiro (Sylabs)
Omar Paul (AWS)
Lahiru Dissanayake (AWS)
Samuel Karp (AWS)
Niaz Khan (AWS)
Miloslav Trmač (Red Hat)
add youself

Agenda Items:

Remind ourselves to post agenda items the Friday before :)
KubeCon Schedule update - Amye is working with the KubeCon schedule folks
Repo update & discussion
Requirement of signing locally
Break out

Notes:

https://www.docker.com/blog/community-collaboration-on-notary-v2/
Kubecon Amsterdam planning is being looked at. Currently looks like mid-week (Mar 30-Apr 2), Steve is working with Amy to find a location and times.
Breakout updates:
- Threat Model (Justin)
- Key Managment (Justin)
  - AWS can help with the key management/crypto org participating
- Integration with OCI & the Spec (Vincent)
  - Some early conversation with between Vincent & Jon. Would like to get Distribtuion 1.0 get out first, and we’ll be additive.
- Scenarios (Steve)
  - In progress: https://github.com/notaryproject/requirements/pull/1
- Use Cases
- UX (Omar)
  - Holding pattern for a couple of weeks as the scenarios and use cases flesh out
Steve - local signing, keys, registries
- Sam - local signing makes sense
Glossary of terms is needed. Define terms so we can use them in discussion and everyone knows what they mean. Key, Signature, Artifact, Key Store, Artifact Store, Annotation, Manifest, Metadata, Artifact Version, Tag, …
Air-gapped/disconnected environments is a scenario that should be spec’d.
Artifact names and signature references:
When you sign a manifest, are we signing all the annotations? If so, then as annotations are added, consider an exampe scenario that vendor annotates, then subsequently some process adds(not change of image) something, that should not invalidate the vendor signature)
Mixing signed and unsigned annotations is out of scope.
Spec should refer to orhestrators generically.
fx:1.0 scenario was too abstract in some areas to articulate which element of the stack would enforce the scenario.

January 13, 2020

video available: https://youtu.be/_cNtDvaU-J8

Attendees:

Steve Lasker (Azure)
Justin Cormack (Docker)
Omar Paul (AWS)
Tue Tran (AWS)
Lahiru (AWS)
Dave Trudgian (Sylabs)
Samuel Karp (AWS)
Stuart Hayton (IBM/ICR)
Vincent Batts
Ian Kaneshiro (Sylabs)
Chad Metcalf
Jon Johnson (Google)
Phil Estes (IBM)
Raja jadeja (AWS)
Mike Brown (IBM)
Miloslav Trmac (RH)
Joseph Schorr (RH/Quay)
Evan Cordell (RH/Quay)

Agenda Items:

Holiday Update (Justin)
Scenarios (Steve)

Notes:

(Justin) - Org things
- Justin created a notary project under github https://github.com/notaryproject/
- Requirements repo created at https://github.com/notaryproject/requirements/
(Justin) How do we account for the UX of how someone signs and/or validates signatures?
Steve/Justin - how do we account for general signatures? Should a customer have to state which signatures they support before? Or, is there a * like scenario where they require a signature, but not a specific signature? Or, is this up to specific hosts to implement? This has remnants of trust on first use
Need to account for mirroring scenario (steve)
Stuart/Justin: How do we account for heirarchy (root of trust) scenarios?
Need to account for revoking signature scenarios, including mirrored scenarios (steve)
Steve - have we thought about root signatures being in one-place, while the signed artifacts are in a different registry?
- Justin - this was part of Notary v1, with the China mirror.
- Miloslav - this is less of signature issue, but more of a content transport redirection scenario
- Justin - we did implement this for things like edge/semi disconnected scenarios.
Miloslav - does scenario #1 imply the artifact can be signed before it’s compressed?
Sam - while the current docker implementation doesn’t store the compressed format, containerd does support both.
Justin - we do really want Docker to work this way (containerd), we just haven’t had a chance yet. Mainly a complicated migration scenario. Derek has a PR opened. It’s why we have this weird buildx plug-in.
David - we have signing and validation embedded into the single file. We currently work through the registry through ORAS.
Steve - we’ll account for whatever Notary v2 goes with into ORAS.
Stuart - mirroring: Justin was talking about the home location problem. Questions on the history of the name.
- Justin - do you need to know the history of the name? If it’s my image docker.io/justincormack/foo, I may use docker.io/justincormack for my signing key/authority. However, other vendors like Microsoft may have it’s own key.
- Joey - I agree, the name seems to be unimportant. If docker wants to sign every image, they can with docker.io/centralsignature, or there’s a specific signature. It’s up the client for which signatures they want to trust
- Justin - we definitley can’t have anything change when moved between regsitries
- Steve - we’re talkinga about seperating the signature name from the registry it’s stored within.
- Mirek - the difference between signed “what the content is” and location is important. If the user asks for a specific version, they should get the specific version they asked for.
- Joey - need to think about keys being tied to versions. I don’t want to end up with the tag name being put into the manifest. If one manifest list can refer to a remote manifest, … then it’s up to each user to make a determination on how they sign things. Expect most users will want to trust a general key, not a specific version. But, customers can opt-into the narrowness of what they need. Perhaps a key for major version, with an annotation for a minor version. Want to get away from the tag name being canonicalized into the annotations.
- Steve - the scnearios capture naming can be different as the artifact moves.
- Justin - most people do want to know by tag, and they’re running mysql:3.8, they really get something that was tagged mysql:3.8, and not something mysql:3.4
- Steve - how much should we lean into SBOM, vs tied signatures to specific artfiacts. Should we dictate a flow, or enable a flow?
- Justin - we definelty want to be flexible, but we defintiley want some standard policy/framework to apply the kind of policies they want. It’s important to know it’s mysql, but also what version is also important.

Notes from slack: From Red Hat NYC to Everyone: 11:01 AM We need to leave now, unfortunately, but wanted to comment that name resolution is already the job of the registry; it seems weird to have a second system to replace the very purpose of the registry that’s part of the reason we have a concern with how Notary V1 worked From Miloslav Trmač to Everyone: 11:01 AM The registry (or the registries involved, or the backing storage) is by definition untrusted or we, for the most part, don’t need signatures

Docs: notation

Mon, 01 Jan 0001 00:00:00 +0000

notation

Notation - a tool to sign and verify artifacts

Options

 -h, --help help for notation

Docs: notation certificate

Mon, 01 Jan 0001 00:00:00 +0000

notation certificate

Manage certificates in trust store

Synopsis

Manage certificates in trust store for signature verification.

Options

 -h, --help help for certificate

Docs: notation certificate add

Mon, 01 Jan 0001 00:00:00 +0000

notation certificate add

Add certificates to the trust store

Synopsis

Add certificates to the trust store

notation certificate add --type <type> --store <name> [flags] <cert_path>...

Examples

# Add a certificate to the "ca" type of a named store "acme-rockets":
notation cert add --type ca --store acme-rockets acme-rockets.crt
# Add a certificate to the "signingAuthority" type of a named store "wabbit-networks":
notation cert add --type signingAuthority --store wabbit-networks wabbit-networks.pem

Options

 -h, --help help for add
-s, --store string specify named store
-t, --type string specify trust store type, options: ca, signingAuthority

Docs: notation certificate delete

Mon, 01 Jan 0001 00:00:00 +0000

notation certificate delete

Delete certificates from the trust store

Synopsis

Delete certificates from the trust store

notation certificate delete --type <type> --store <name> [flags] (--all | <cert_fileName>)

Examples

# Delete all certificates with "ca" type from the trust store "acme-rockets":
notation cert delete --type ca --store acme-rockets --all
# Delete certificate "cert1.pem" with "signingAuthority" type from trust store wabbit-networks:
notation cert delete --type signingAuthority --store wabbit-networks cert1.pem
# Delete all certificates with "ca" type from the trust store "acme-rockets", without prompt for confirmation:
notation cert delete --type ca --store acme-rockets -y --all

Options

 -a, --all delete all certificates in the named store
-h, --help help for delete
-s, --store string specify named store
-t, --type string specify trust store type, options: ca, signingAuthority
-y, --yes do not prompt for confirmation

Docs: notation certificate generate-test

Mon, 01 Jan 0001 00:00:00 +0000

notation certificate generate-test

Generate a test RSA key and a corresponding self-signed certificate.

Synopsis

Generate a test RSA key and a corresponding self-signed certificate

Example - Generate a test RSA key and a corresponding self-signed certificate named “wabbit-networks.io”: notation cert generate-test “wabbit-networks.io”

Example - Generate a test RSA key and a corresponding self-signed certificate, set RSA key as a default signing key: notation cert generate-test –default “wabbit-networks.io”

notation certificate generate-test [flags] <common_name>

Options

 -b, --bits int RSA key bits (default 2048)
--default mark as default signing key
-h, --help help for generate-test

Docs: notation certificate list

Mon, 01 Jan 0001 00:00:00 +0000

notation certificate list

List certificates in the trust store

Synopsis

List certificates in the trust store

notation certificate list [flags]

Examples

# List all certificate files stored in the trust store
notation cert ls
# List all certificate files of trust store "acme-rockets"
notation cert ls --store "acme-rockets"
# List all certificate files from trust store of type "ca"
notation cert ls --type ca
# List all certificate files from trust store "wabbit-networks" of type "signingAuthority"
notation cert ls --type signingAuthority --store "wabbit-networks"

Options

 -d, --debug debug mode
-h, --help help for list
-s, --store string specify named store
-t, --type string specify trust store type, options: ca, signingAuthority
-v, --verbose verbose mode

Docs: notation certificate show

Mon, 01 Jan 0001 00:00:00 +0000

notation certificate show

Show certificate details given trust store type, named store, and certificate file name. If the certificate file contains multiple certificates, then all certificates are displayed

Synopsis

Show certificate details of given trust store name, trust store type, and certificate file name. If the certificate file contains multiple certificates, then all certificates are displayed

notation certificate show --type <type> --store <name> [flags] <cert_fileName>

Examples

# Show details of certificate "cert1.pem" with type "ca" from trust store "acme-rockets":
notation cert show --type ca --store acme-rockets cert1.pem
# Show details of certificate "cert2.pem" with type "signingAuthority" from trust store "wabbit-networks":
notation cert show --type signingAuthority --store wabbit-networks cert2.pem

Options

 -d, --debug debug mode
-h, --help help for show
-s, --store string specify named store
-t, --type string specify trust store type, options: ca, signingAuthority
-v, --verbose verbose mode

Docs: notation completion

Mon, 01 Jan 0001 00:00:00 +0000

notation completion

Generate the autocompletion script for the specified shell

Synopsis

Generate the autocompletion script for notation for the specified shell. See each sub-command’s help for details on how to use the generated script.

Options

 -h, --help help for completion

Docs: notation completion bash

Mon, 01 Jan 0001 00:00:00 +0000

notation completion bash

Generate the autocompletion script for bash

Synopsis

Generate the autocompletion script for the bash shell.

This script depends on the ‘bash-completion’ package. If it is not installed already, you can install it via your OS’s package manager.

To load completions in your current shell session:

source <(notation completion bash)

To load completions for every new session, execute once:

Linux:

notation completion bash > /etc/bash_completion.d/notation

macOS:

notation completion bash > $(brew --prefix)/etc/bash_completion.d/notation

You will need to start a new shell for this setup to take effect.

notation completion bash

Options

 -h, --help help for bash
--no-descriptions disable completion descriptions

Docs: notation completion fish

Mon, 01 Jan 0001 00:00:00 +0000

notation completion fish

Generate the autocompletion script for fish

Synopsis

Generate the autocompletion script for the fish shell.

To load completions in your current shell session:

notation completion fish | source

To load completions for every new session, execute once:

notation completion fish > ~/.config/fish/completions/notation.fish

You will need to start a new shell for this setup to take effect.

notation completion fish [flags]

Options

 -h, --help help for fish
--no-descriptions disable completion descriptions

Docs: notation completion powershell

Mon, 01 Jan 0001 00:00:00 +0000

notation completion powershell

Generate the autocompletion script for powershell

Synopsis

Generate the autocompletion script for powershell.

To load completions in your current shell session:

notation completion powershell | Out-String | Invoke-Expression

To load completions for every new session, add the output of the above command to your powershell profile.

notation completion powershell [flags]

Options

 -h, --help help for powershell
--no-descriptions disable completion descriptions

Docs: notation completion zsh

Mon, 01 Jan 0001 00:00:00 +0000

notation completion zsh

Generate the autocompletion script for zsh

Synopsis

Generate the autocompletion script for the zsh shell.

If shell completion is not already enabled in your environment you will need to enable it. You can execute the following once:

echo "autoload -U compinit; compinit" >> ~/.zshrc

To load completions in your current shell session:

source <(notation completion zsh)

To load completions for every new session, execute once:

Linux:

notation completion zsh > "${fpath[1]}/_notation"

macOS:

notation completion zsh > $(brew --prefix)/share/zsh/site-functions/_notation

You will need to start a new shell for this setup to take effect.

notation completion zsh [flags]

Options

 -h, --help help for zsh
--no-descriptions disable completion descriptions

Docs: notation inspect

Mon, 01 Jan 0001 00:00:00 +0000

notation inspect

Inspect all signatures associated with the signed artifact

Synopsis

Inspect all signatures associated with the signed artifact

notation inspect [reference] [flags]

Examples

# Inspect signatures on an OCI artifact identified by a digest:
notation inspect <registry>/<repository>@<digest>
# Inspect signatures on an OCI artifact identified by a tag (Notation will resolve tag to digest):
notation inspect <registry>/<repository>:<tag>
# Inspect signatures on an OCI artifact identified by a digest and output as json:
notation inspect --output json <registry>/<repository>@<digest>
# [Experimental] Inspect signatures on an OCI artifact identified by a digest using the Referrers API, if not supported (returns 404), fallback to the Referrers tag schema
notation inspect --allow-referrers-api <registry>/<repository>@<digest>

Options

 --allow-referrers-api [Experimental] use the Referrers API to inspect signatures, if not supported (returns 404), fallback to the Referrers tag schema
-d, --debug debug mode
-h, --help help for inspect
--insecure-registry use HTTP protocol while connecting to registries. Should be used only for testing
--max-signatures int maximum number of signatures to evaluate or examine (default 100)
-o, --output string output format, options: 'json', 'text' (default "text")
-p, --password string password for registry operations (default to $NOTATION_PASSWORD if not specified)
-u, --username string username for registry operations (default to $NOTATION_USERNAME if not specified)
-v, --verbose verbose mode

Docs: notation key

Mon, 01 Jan 0001 00:00:00 +0000

notation key

Manage keys used for signing

Synopsis

Manage keys used for signing

Examples

# Add a key to signing key list:
notation key add --plugin <plugin_name> --id <key_id> <key_name>
# List keys used for signing:
notation key ls
# Update the default signing key:
notation key set --default <key_name>
# Delete the key from signing key list:
notation key delete <key_name>...

Options

 -h, --help help for key

Docs: notation key add

Mon, 01 Jan 0001 00:00:00 +0000

notation key add

Add key to Notation signing key list

notation key add --plugin <plugin_name> [flags] <key_name>

Options

 -d, --debug debug mode
--default mark as default
-h, --help help for add
--id string key id (required if --plugin is set)
--plugin string signing plugin name
--plugin-config stringArray {key}={value} pairs that are passed as it is to a plugin, refer plugin's documentation to set appropriate values
-v, --verbose verbose mode

Docs: notation key delete

Mon, 01 Jan 0001 00:00:00 +0000

notation key delete

Remove key from Notation signing key list

notation key delete [flags] <key_name>...

Options

 -d, --debug debug mode
-h, --help help for delete
-v, --verbose verbose mode

Docs: notation key list

Mon, 01 Jan 0001 00:00:00 +0000

notation key list

List keys used for signing

notation key list [flags]

Options

 -h, --help help for list

Docs: notation key update

Mon, 01 Jan 0001 00:00:00 +0000

notation key update

Update key in Notation signing key list

notation key update [flags] <key_name>

Options

 -d, --debug debug mode
--default mark as default
-h, --help help for update
-v, --verbose verbose mode

Docs: notation list

Mon, 01 Jan 0001 00:00:00 +0000

notation list

List signatures of the signed artifact

Synopsis

List all the signatures associated with signed artifact

notation list [flags] <reference>

Options

 --allow-referrers-api [Experimental] use the Referrers API to list signatures, if not supported (returns 404), fallback to the Referrers tag schema
-d, --debug debug mode
-h, --help help for list
--insecure-registry use HTTP protocol while connecting to registries. Should be used only for testing
--max-signatures int maximum number of signatures to evaluate or examine (default 100)
--oci-layout [Experimental] list signatures stored in OCI image layout
-p, --password string password for registry operations (default to $NOTATION_PASSWORD if not specified)
-u, --username string username for registry operations (default to $NOTATION_USERNAME if not specified)
-v, --verbose verbose mode

Docs: notation login

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

notation login [flags] <server>

Examples

# Login with provided username and password:
notation login -u <user> -p <password> registry.example.com
# Login using $NOTATION_USERNAME $NOTATION_PASSWORD variables:
notation login registry.example.com

Options

 -d, --debug debug mode
-h, --help help for login
--insecure-registry use HTTP protocol while connecting to registries. Should be used only for testing
-p, --password string password for registry operations (default to $NOTATION_PASSWORD if not specified)
--password-stdin take the password from stdin
-u, --username string username for registry operations (default to $NOTATION_USERNAME if not specified)
-v, --verbose verbose mode

Docs: notation logout

Mon, 01 Jan 0001 00:00:00 +0000

notation logout

Log out from the logged in registries

notation logout [flags] <server>

Options

 -d, --debug debug mode
-h, --help help for logout
-v, --verbose verbose mode

Docs: notation plugin

Mon, 01 Jan 0001 00:00:00 +0000

notation plugin

Manage plugins

Options

 -h, --help help for plugin

Docs: notation plugin list

Mon, 01 Jan 0001 00:00:00 +0000

notation plugin list

List installed plugins

Synopsis

List installed plugins

notation plugin list [flags]

Examples

# List installed Notation plugins:
notation plugin ls

Options

 -h, --help help for list

Notary Project | A set of specifications and tools intended to provide a cross-industry standard for securing software supply chains. – Notary Project documentation

Docs: Authenticate with OCI-compliant registries

Configure a credentials store

Important

Configure environment variables to authenticate to an OCI-compliant registry

Warning

Configure config.json to authenticate to an OCI-compliant registry

Warning

Use notation login to authenticate to an OCI-compliant registry

Note

Use notation logout to log out of an OCI-compliant registry

Warning

OCI-compliant registries

Docs: Create a trust policy and verify artifacts

Create an example registry with an image

Warning

Note

Create example certificates and sign the image

Warning

Create a trust policy

Note

Verify image signatures using the trust policy

Cleanup

Remove the notation configuration

Remove the registry

Docs: Install the notation CLI

Warning

Download and install the CLI for Linux

Download and install the CLI for macOS

Download and install the CLI for Windows

Additional configuration

Important

Docs: Overview

Introduction

Project status

Security

Community

Docs: Quickstart: Sign and validate a container image

Playground

Prerequisites

Create an OCI-compatible registry

Note

Add an image to the OCI-compatible registry

Note

List the signatures associated with the container image

Generate a test key and self-signed certificate

Warning

Note

Sign the container image

Create a trust policy

Verify the container image

Cleanup

Docs: Securely develop plugins for Notation

Important

General security guidance

Securely distributing plugins

Docs: Manage trust policies

Docs: Quickstart: Sign and validate a non-image artifact

Prerequisites

Create an OCI-compatible registry

Note

Add an image to the OCI-compatible registry

Note

Generate an SBOM for the container image

Attach the SBOM to the container image

List the signatures associated with the SBOM

Generate a test key and self-signed certificate

Warning

Note

Sign the SBOM

Create a trust policy

Verify the container image

Cleanup

Docs: Sign and verify artifacts in CI/CD and GitOps

CI/CD

GitOps

Docs: Uninstall the notation CLI and its configuration

Important

Remove the notation CLI

Remove the additional binaries

Configure `config.json` to authenticate to an OCI-compliant registry

Use `notation login` to authenticate to an OCI-compliant registry

Use `notation logout` to log out of an OCI-compliant registry