Notary

Notary is a concrete implementation of TUF, a flexible security specification designed to protect against key compromise and repository attacks. It manages a hierarchical key structure with distinct roles—root, targets, snapshot, and timestamp—each with specific trust responsibilities. This separation of duties ensures that compromising a single key does not grant an attacker the ability to sign arbitrary content. The framework uses a threshold signature scheme, requiring a configurable number of keys to sign critical metadata before it is considered valid, preventing unilateral malicious actions.

Notary is the backend service that powers Docker Content Trust (DCT). When DCT is enabled, the Docker client communicates with a Notary server to verify the digital signature of a tagged image before pulling or running it. This process cryptographically binds a publisher's identity to an image digest, ensuring the image has not been tampered with since publication. Key operational commands include:

• DOCKER_CONTENT_TRUST=1: Environment variable to globally enforce signature verification.
• docker trust sign: Command for publishers to sign and push a tagged image.
• docker trust inspect: Command to view signers and signature metadata for an image.

Notary supports delegation, allowing a repository owner to delegate signing authority for specific image tags or namespaces to other verified parties without sharing the primary targets key. This is critical for large organizations where different teams manage separate software components. A delegation role is defined with a set of trusted public keys and a list of path patterns it is authorized to sign. This enables a secure, scalable model where a platform team can delegate the signing of team-a/* images to Team A's specific keys, maintaining a strict chain of custody.

Notary's security model relies on a strict separation between offline root keys and online repository keys. The root key, which establishes the ultimate trust anchor for a repository, is intended to be generated and stored on an air-gapped hardware security module (HSM) or a permanently disconnected device. Day-to-day signing operations use lower-privilege targets and delegation keys. This architecture ensures that even if the online Notary service is fully compromised, an attacker cannot rotate the root of trust or sign content for new, unauthorized namespaces.

To prevent rollback attacks—where an attacker serves an older, validly-signed but vulnerable version of metadata—Notary employs timestamp and snapshot roles. The timestamp key signs a frequently-expiring file that indicates the latest version of the snapshot metadata. The snapshot key signs a manifest listing the current versions of all other metadata files. Clients verify these timestamps, ensuring they are receiving the most recent content. If a timestamp is stale, the client rejects the update, guaranteeing freshness in the trust chain.

The evolution to Notary v2 decouples signing from a central server, aligning with the OCI Distribution Specification. Instead of a proprietary protocol, signatures are stored as standard OCI Artifacts alongside the image in any compliant registry. This allows for a serverless signing workflow using tools like notation, where a publisher creates a signature artifact and pushes it directly to the registry. Verification is performed by resolving the image's referrers API to find and validate the attached signature manifest, eliminating the need for a separate Notary service for core signing operations.

A security mechanism that uses digital signatures to ensure only authorized, untampered container images are pulled and executed. Notary is the primary implementation enabling content trust in Docker registries.

• Enforces image authenticity at runtime
• Prevents man-in-the-middle registry attacks
• Validates publisher identity before image pull
• Integrates with Docker Content Trust (DOCKER_CONTENT_TRUST=1)

A tool under the Sigstore project used to cryptographically sign container images and OCI artifacts. Unlike Notary's TUF-based approach, Cosign stores signatures directly alongside images in the registry.

• Supports keyless signing via OIDC
• Generates signatures in OCI-compliant format
• Works with any OCI registry without external services
• Complements Notary for defense-in-depth signing strategies

A free, open-source public good service enabling automated, keyless signing and verification of software artifacts. It uses OpenID Connect identities and a transparent log (Rekor) to provide non-repudiation.

• Eliminates long-term key management
• Provides public auditability via transparency logs
• Integrates with Fulcio certificate authority
• Often used alongside Notary for developer-friendly signing workflows

A cryptographically signed, verifiable statement about a container image, such as an SBOM or vulnerability scan result. Attestations are stored alongside the image in the registry for automated policy enforcement.

• Proves build provenance (who built it, how, when)
• Links SBOMs to specific image digests
• Enables policy-based admission in Kubernetes
• Uses in-toto attestation format for standardization

A deploy-time security control that enforces strict signature validation before containers can run. It ensures only images signed by trusted authorities during the build process reach production clusters.

• Integrates with Kubernetes admission controllers
• Enforces deploy-time policy (not just pull-time)
• Requires valid Notary or Cosign signatures
• Creates an immutable trust boundary at deployment

A security framework (Supply-chain Levels for Software Artifacts) providing a tamper-proof, attestable record of the build process. SLSA provenance answers: who built the image, from what source, using which build pipeline?

• Defines four progressive security levels (L1-L4)
• Requires hermetic, isolated builds at higher levels
• Generates verifiable provenance attestations
• Complements Notary signatures with build integrity metadata