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

You can integrate the notation CLI with DigiCert® Software Trust Manager by using the notation plugin (notation-digicert-stm) to securely manage your signing keys. The plugin ensures that cryptographic operations are performed using keys stored and protected within Software Trust Manager. This approach enables you to sign and verify OCI container images while delegating key protection and lifecycle management to a trusted service.

Step 1: Configure notation policies

Insecure / private registries

If your registry uses HTTP or a self-signed TLS certificate, add it to notation's config.json so notation doesn’t reject the connection.

Config file location:

Platform	Path
Windows	`~/.config/notation/config.json`
Linux and macOS	`%APPDATA%\notation\config.json`

Add the registry to insecureRegistries:

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

작은 정보

For TLS-secured private registries with a self-signed certificate, add the CA to your OS trust store instead. Avoid insecureRegistries in production environments.

Trust policy

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:

Platform	Path
Windows	`%APPDATA%\notation\trustpolicy.json`
Linux and macOS	`~/.config/notation/trustpolicy.json`

작은 정보

Important limitations:

Notation doesn’t support partial wildcards like registry.example.com/*
"*" is allowed as a global wildcard in trust policies
Always use full repository paths for scoped policies

Production policy (strict — recommended)

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"
      ]
    }
  ]
}

작은 정보

trustedIdentities: Must match the Subject field of the signing certificate exactly, in comma-separated RFC 4514 DN format. Use notation inspect on a signed image to find the exact subject string.

Also see: Trust store and trust policy specification

Add your CA certificate to the notation trust store

For strict or permissive verification, notation must trust the CA that issued the signing certificate.

Obtain the PEM CA certificate from your Software Trust Manager account or PKI administrator.
Save the certificate as digicert-stm-ca.pem.

Add it to notation's trust store:

Verify the certificate was added:

notation cert list

Expected output:

STORE TYPE   STORE NAME        CERT NAME
ca           digicert-stm-ca   digicert-stm-ca.pem

[Optional]: Add a timestamp authority (TSA) root certificate:

If you use --timestamp-url when signing, trust the TSA's root CA too:

notation cert add \
  --type tsa \
  --store my-tsa-root \
  tsa-root-ca.pem

Reference both in the trust policy:

"trustStores": [
  "ca:digicert-stm-ca",
  "tsa:my-tsa-root"
],
"signatureVerification": {
  "level": "strict",
  "override": {
    "authenticTimestamp": "enforced"
  }
}

Step 2: Sign a container image

Ensure the image is already pushed to your registry.

Find your keypair alias

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

Sign the image

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

Sign using an alias (recommended)

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

Sign using a keypair UUID

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

Select a signature format

Notation supports two envelope formats:

JSON Web Signature (JWS)
CBOR Object Signing and Encryption (COSE)

작은 정보

Use COSE if your downstream tooling or policy requires it. Alternatively, JWS is widely supported.

Sign with a timestamp authority

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:

Provider	URL
DigiCert	http://timestamp.digicert.com
Microsoft	http://timestamp.acs.microsoft.con
GlobalSign	http://timestamp.globalsign.com/scripts/timstamp.dll

작은 정보

When using a timestamp, you must also trust the TSA's root CA in your trust store and reference it in the trust policy.

Step 3: Verify signature

Inspect a signature's metadata

notation inspect registry.example.com/myapp:v1.0.0

This shows the complete signature details:

registry.example.com/myapp@sha256:8637808eae0e7c2a...
└── application/jose+json
    ├── digest: sha256:3e4c5f6d...
    ├── signature algorithm: RSASSA-PSS-SHA-256
    ├── signed attributes
    │   ├── content type: application/vnd.cncf.notary.payload.v1+json
    │   └── signing time: Fri Mar 20 10:15:23 2026
    └── certificate chain
        ├── SHA256 fingerprint: 4a:5b:6c:...
        │   issued to: CN=My Signing Cert, O=My Org, C=US
        │   issued by: CN=DigiCert STM CA, O=DigiCert, C=US
        │   expiry: Sat Mar 20 10:15:23 2027
        └── ...

Use the issued to value verbatim as the trustedIdentities entry in your trust policy.

List all signatures on an artifact

notation list registry.example.com/myapp:v1.0.0

Output:

registry.example.com/myapp@sha256:8637808eae0e7c2a...
└── application/jose+json
    └── sha256:3e4c5f6d...

Troubleshooting

Plugin not found by notation

Error

plugin "digicert-stm" not found

Solution

Run:
```
notation plugin list
```
Verify the binary is in the correct directory:
1. Windows: dir $env:APPDATA\notation\plugins\digicert-stm\
2. Linux/macOS: ls ~/.config/notation/plugins/digicert-stm/
On Linux/macOS, to confirm the binary is executable, run:
```
chmod +x notation-digicert-stm
```
The binary name must be exactly notation-digicert-stm (or notation-digicert-stm.exe on Windows); Notation derives the plugin name from the binary name.

Authentication failures in plugin logs

Error

failed to setup STM client

401 Unauthorized

Solution

Confirm that all four required environment variables are exported in the same shell session where you run:
```
notation sign
```

Verify the certificate password:

openssl pkcs12 -info -in $SM_CLIENT_CERT_FILE -passin env:SM_CLIENT_CERT_PASSWORD

The API key must have signing and View certificate permissions in Software Trust Manager.

Keypair not found

Error

failed to get keypair: 404 Not Found

Solution

Run:

smctl keypair list

작은 정보

Aliases are case-sensitive.

Trust policy rejects the signature

Error

signature verification failed: no applicable trust policy

trusted identity did not match

Solution

Run:
```
notation inspect <image-ref>
```
Copy the exact certificate subject string.
Paste it verbatim into trustedIdentities in your trust policy, prefixed with x509.subject:.
Confirm the registry scope in registryScopes matches the image reference exactly. Partial wildcards (registry.example.com/*) aren’t valid, use "*" for global scope or a full repository path.
Verify the CA cert is in the trust store:
```
notation cert list
```

Signature verification fails after certificate expiry

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

Enable debug logging

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.

이 섹션의 내용: