Notary — Container Image Signing and Verification for Supply Chain Security

Introduction

Notary is a CNCF project that defines how container images and OCI artifacts are signed, stored, and verified. The notation CLI implements the Notary v2 specification, enabling developers and organizations to establish a chain of trust for their container supply chain.

What Notary Does

• Signs OCI container images and artifacts with cryptographic signatures stored alongside the image in the registry
• Verifies signatures against configurable trust policies before images are deployed
• Supports pluggable signature formats and key management systems through a provider model
• Stores signatures as OCI artifacts in standard registries without requiring separate infrastructure
• Integrates with admission controllers to enforce signature verification at deployment time

Architecture Overview

The Notary v2 specification separates signing, storage, and verification into distinct concerns. Signatures are stored as OCI reference artifacts linked to the signed image's manifest digest. The notation CLI handles signing using pluggable key providers (local keys, cloud KMS, or hardware tokens). Verification evaluates a trust policy document that defines which identities and registries are trusted. This design keeps signatures portable across registries and avoids vendor lock-in.

Self-Hosting & Configuration

• Install the notation CLI from GitHub releases or via Homebrew on macOS
• Generate a signing key with notation cert generate-test for development or configure a cloud KMS plugin for production
• Create a trust policy file (~/.config/notation/trustpolicy.json) defining trusted identities and registries
• Push signed images to any OCI-compliant registry that supports the referrers API (Docker Hub, ACR, ECR, Harbor)
• Deploy the Ratify admission controller in Kubernetes to enforce signature verification on pod creation

Key Features

• Standards-based signing using the OCI reference artifact specification for portability
• Pluggable key management supports AWS KMS, Azure Key Vault, HashiCorp Vault, and local keys
• Trust policy engine allows fine-grained control over which signatures are accepted per registry and scope
• Signatures are stored in standard OCI registries without requiring additional signature storage infrastructure
• CNCF-backed specification ensures broad ecosystem support and long-term stability

Comparison with Similar Tools

• Cosign (Sigstore) — keyless signing with transparency log integration; Notary focuses on traditional PKI and enterprise key management workflows
• Docker Content Trust (DCT) — the original Notary v1 used by Docker; Notary v2 is a ground-up redesign with OCI-native signature storage
• in-toto — focuses on software supply chain attestation layout; Notary handles the signing and verification layer specifically
• TUF (The Update Framework) — provides secure software update distribution; Notary v2 focuses specifically on OCI artifact signing

FAQ

Q: What is the difference between Notary v1 and v2? A: Notary v1 (TUF-based) required a separate Notary server. Notary v2 stores signatures directly in OCI registries as reference artifacts, simplifying the architecture.

Q: Can Notary work with keyless signing like Sigstore? A: Notary v2 is pluggable. While it defaults to traditional key-based signing, plugins can integrate with identity-based or keyless signing providers.

Q: Which registries support Notary v2 signatures? A: Most major registries now support the OCI referrers API, including Docker Hub, Azure Container Registry, Amazon ECR, and Harbor.

Q: How do I enforce signed images in Kubernetes? A: Deploy the Ratify project as an admission controller alongside Gatekeeper or Kyverno to validate Notary signatures before allowing pod creation.

Sources

• https://github.com/notaryproject/notary
• https://notaryproject.dev