Skip to content

Notation⚓︎

Notation is a CNCF project that provides a standard for signing and verifying container images and other OCI artifacts using digital signatures. It is part of the Notary Project, also known as Notary V2, which builds upon lessons learned from the original Notary (V1) project. Notation provides a simple command-line experience for signing OCI artifacts and a set of libraries for integration into larger systems.

Unlike Notary V1 which relies on The Update Framework (TUF), Notation uses a simpler trust model based on X.509 certificates and certificate chains. This makes it easier to integrate with existing PKI infrastructure and certificate management systems. Signatures are stored as OCI artifacts in the same registry as the signed container images, eliminating the need for a separate trust server.

Connaisseur supports validating Notation signatures based on X.509 certificates configured as trust roots. The validator can verify signatures created by the Notation CLI or any compatible signing tools that implement the Notation specification.

Basic usage⚓︎

To get started with Notation, you'll need to install the Notation CLI and create signing certificates. The Notation documentation provides comprehensive guidance for installation and setup.

Creating certificates⚓︎

For testing purposes, you can create a self-signed certificate:

# Create a self-signed certificate
notation cert generate-test --default "mykey"

Signing images⚓︎

Once you have certificates configured, you can sign and push container images:

# Push the image
docker image push <IMAGE_URI>

# Sign with a specific certificate
notation sign --key "mykey" <IMAGE_URI>

Creating trust policy⚓︎

Before verifying the container image, create a trust policy to match certain images to their respective keys, used for verification.

Create a JSON file with your trust policy:

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

Use notation policy import to import the policy:

notation policy import ./trustpolicy.json

Verifying signatures⚓︎

You can verify signatures using the Notation CLI:

# Verify an image signature
notation verify <IMAGE_URI>

Configuring Connaisseur⚓︎

To use Connaisseur with Notation, configure a validator in charts/connaisseur/values.yaml with your signing certificate as a trust root. The entry in .application.validators should look like this:

charts/connaisseur/values.yaml