Coming soon: Sign container images with Notation CLI using Notation plugin (recommended)

If your registry uses HTTP or a self-signed TLS certificate, add it to Notation's config.json so Notation does not reject the connection.

Config file location:

Add the registry to insecureRegistries:

{
  "insecureRegistries": [
    "localhost:5000",
    "registry.internal.mycompany.com"
  ]
}

The trust policy specifies which registries to trust, which CA or identity must have signed the artifact, and what level of verification to enforce.

Trust policy file location:

Enforces full chain verification, identity matching, and revocation checking. Replace values in angle brackets with your own.

{
  "version": "1.0",
  "trustPolicies": [
    {
      "name": "stm-production-policy",
      "registryScopes": [
        "registry.example.com/myteam/myapp"
      ],
      "signatureVerification": {
        "level": "strict"
      },
      "trustStores": [
        "ca:digicert-stm-ca"
      ],
      "trustedIdentities": [
        "x509.subject: CN=My Signing Cert, O=My Org, C=US"
      ]
    }
  ]
}

You can locate the keypair alias via DigiCert​​®​​ Software Trust Manager or Signing Manager Controller (SMCTL).

smctl keypair list

Notation resolves the tag to a content-addressable digest and signs that digest.

notation sign \
  --plugin digicert-stm \
  --id <key-alias> \
  <registry>/<repository>:<tag>

notation sign \
  --plugin digicert-stm \
  --id 3f46a2c1-8b9d-4e72-a3f1-0123456789ab \
  registry.example.com/myapp:v1.0.0

Notation supports two envelope formats: 

notation sign \
  --plugin digicert-stm \
  --id my-rsa-4096-key \
  --signature-format jws \
  registry.example.com/myapp:v1.0.0

notation sign \
  --plugin digicert-stm \
  --id my-rsa-4096-key \
  --signature-format cose \
  registry.example.com/myapp:v1.0.0

Embedding an RFC 3161 timestamp means signatures remain verifiable even after the signing certificate expires.

notation sign \
  --plugin digicert-stm \
  --id my-rsa-4096-key \
  --timestamp-url http://timestamp.digicert.com \
  --timestamp-root-cert tsa-root-ca.pem \
  registry.example.com/myapp:v1.0.0

Commonly used TSA endpoints:

Error

plugin "digicert-stm" not found

Solution

Error

failed to setup STM client

or

401 Unauthorized

Solution

Error

failed to get keypair: 404 Not Found

Solution

Run:

smctl keypair list

Error

signature verification failed: no applicable trust policy

or

trusted identity did not match

Solution

Use a Timestamp Authority (TSA) when signing. The embedded timestamp proves the signature was created while the certificate was valid, regardless of when verification occurs.

notation sign \
  --plugin digicert-stm \
  --id my-rsa-4096-key \
  --timestamp-url http://timestamp.digicert.com \
  --timestamp-root-cert tsa-root-ca.pem \
  registry.example.com/myapp:v1.0.0

export SM_LOG_LEVEL=debug
export SM_LOG_OUTPUT=stdout
notation sign --plugin digicert-stm --id my-key registry.example.com/myapp:latest

Logs are also written to $SM_HOME/logs/sm-client.log by default.