Image Signing (Notary v2 / Cosign) in Docker
How a cryptographic signature attached to a container image lets anyone downstream prove exactly who published it and that not a single byte has changed since — without trusting the registry itself at all.
When a container image gets pulled and deployed into production, an implicit trust decision is being made every single time, whether anyone consciously thinks about it or not: trust that the image genuinely came from the organization or maintainer it claims to have come from, and trust that nothing has tampered with it between the moment it was built and the moment it landed on a production server. For most of Docker’s history, that trust rested entirely on the security of the registry itself and the network path to it — if either was compromised, a malicious image could be substituted with no way for a downstream consumer to detect the swap. Image signing closes that gap by attaching a cryptographic signature to an image, one that mathematically proves both who published it and that its content is exactly, byte-for-byte, what that publisher actually built. This guide walks through what image signing actually verifies, how the two major modern approaches — Notary v2 and Cosign — work under the hood, and how to build signature verification into a real deployment pipeline.
Chapter One
ACore Concepts
Before comparing specific tools, it’s worth understanding exactly what a digital signature proves, and what it deliberately does not.
What a signature actually proves
A cryptographic signature over a container image is produced using a private key that only the legitimate publisher holds, applied to a cryptographic hash of the image’s exact content. Anyone who later has the corresponding public key can verify that signature against the same image content, and that verification succeeds if and only if two things are both true: the content has not changed by even a single byte since it was signed, and the signature was genuinely produced by whoever holds that specific private key. This is the entire mechanism, and it is worth being precise about it, because it is easy to overstate what a valid signature actually guarantees.
Think of a wax seal on a historical letter, pressed with a signet ring only the sender owns. Anyone receiving the letter can check the seal’s exact pattern against what they know that sender’s ring produces — if the wax is unbroken and the pattern matches, they can be confident the letter’s contents are exactly as the sender wrote them and that the letter genuinely came from that sender’s household. But the seal says nothing about whether the letter’s contents are wise, truthful, or safe to act on — it only proves authenticity and integrity, nothing about the letter’s actual merit.
What signing does not verify
A valid signature confirms an image’s authenticity and integrity — who published it, and that it hasn’t been altered — but it says nothing whatsoever about whether that image is free of vulnerabilities, well-configured, or safe to run. A legitimate publisher can sign a perfectly authentic image that nonetheless contains a serious security flaw, and the signature will verify successfully regardless, because signing and vulnerability scanning are two entirely separate, complementary concerns addressing different questions.
Treat image signing as answering “did this come from who it claims to have come from, unmodified” — never as answering “is this image safe or good.” Conflating the two is a common and consequential misunderstanding; a comprehensive security posture needs both signature verification and separate vulnerability scanning, working together rather than as substitutes for each other.
Two major approaches: Notary v2 and Cosign
Two significant modern approaches to container image signing have gained wide adoption, each with a distinct philosophy. Notary v2 builds on the earlier Notary project and integrates signature storage directly alongside the image in the registry using a standardized referrers mechanism, aiming for broad interoperability across different registry implementations. Cosign, part of the Sigstore project, takes a different, notably simpler approach, storing signatures as ordinary registry artifacts alongside the image and supporting both traditional long-lived key pairs and a newer, increasingly popular “keyless” signing model tied to short-lived, identity-based certificates rather than a key an individual has to manage and protect indefinitely.
Chapter Two
BArchitecture & Components
Both major approaches share a common conceptual architecture, even though their specific mechanics differ in meaningful ways.
flowchart TB
subgraph BUILD["Build & Sign"]
IMG["Container Image
(content digest)"]
KEY["Private Key
or Short-Lived Identity Cert"]
SIG["Signature
over the digest"]
end
subgraph REG["Registry"]
IMGR["Image Manifest"]
SIGR["Signature
(stored alongside image)"]
end
subgraph VERIFY["Verification at Deploy Time"]
PUB["Public Key / Trusted Identity"]
CHECK["Signature Check"]
RESULT["Verified / Rejected"]
end
IMG --> KEY --> SIG
IMG --> IMGR
SIG --> SIGR
IMGR --> CHECK
SIGR --> CHECK
PUB --> CHECK
CHECK --> RESULT
Signature
The cryptographic proof itself, produced by applying a private key’s signing operation to the image’s content digest, stored in a way that can be retrieved alongside the image it covers.
Traditional Key Pairs
A long-lived private and public key pair, where the private key must be carefully protected and the public key distributed to anyone who needs to verify signatures produced by it.
Keyless Signing (Sigstore Model)
An alternative approach where a short-lived certificate, tied to a verified identity (such as a specific CI pipeline’s identity) rather than a long-term private key, is used to sign, removing the burden of protecting a durable secret indefinitely.
Transparency Log
An append-only, publicly auditable log that records signing events, making it possible to detect if a signature was created at an unexpected or suspicious time, adding an additional layer of accountability beyond the signature itself.
Registry-Native Artifact Storage
Both approaches store signatures as artifacts within the same registry that hosts the image itself, associated with the image through its content digest, so signatures travel with the image across registry copies and mirrors.
Admission / Policy Controller
The component, often integrated into an orchestration platform’s deployment pipeline, responsible for checking a signature’s validity against policy before allowing an image to actually be scheduled and run.
Notary v2’s registry-native referrers model
Notary v2’s design is built specifically around a standardized way for a registry to associate related artifacts — including signatures — with a given image manifest through a referrers mechanism, meaning a signature can be discovered and retrieved by querying the registry for anything related to a specific image digest, without needing a separate, out-of-band signature store. This design goal of broad interoperability across differing registry implementations was a central motivation behind the project.
Cosign’s simplicity-first approach
Cosign was deliberately designed to minimize the operational burden of adopting signing at all, storing signatures using existing, ordinary registry artifact storage conventions rather than requiring registries to implement an entirely new, specialized feature. Its support for keyless signing specifically targets a common practical pain point in traditional signing setups: the ongoing burden of securely generating, storing, rotating, and protecting a long-lived private key, which keyless signing sidesteps by using short-lived, automatically issued certificates instead.
A closer look at exactly what happens during the signing operation itself, and during verification at deployment time.
What actually gets signed
The signature is not applied to the entire, potentially large image content directly; it is applied to the image’s content digest — the same cryptographic hash used throughout the registry’s content-addressable storage model, as covered in the manifest lists topic in this series. Because that digest already uniquely and deterministically represents the image’s exact content, signing the digest is functionally equivalent to signing the full content itself, while being vastly more efficient, since the signing operation only ever needs to process a small, fixed-size hash value rather than the entire image.
The traditional keyed signing flow
In a traditional keyed setup, a publisher generates a key pair once, keeps the private key protected (ideally in a hardware security module or a similarly access-controlled system), and uses that private key to sign each image’s digest at build or release time. The corresponding public key is distributed to anyone who needs to verify those signatures, commonly published through a trusted, separate channel from the registry itself, precisely so that trust in the public key does not depend on trusting the same registry storing the images being verified.
The keyless signing flow
In a keyless setup, rather than a long-lived private key, the signer authenticates through an established identity provider — proving, for instance, that a specific CI pipeline run genuinely belongs to a specific, verified source repository — and receives a short-lived signing certificate tied to that verified identity. That certificate is used to sign the image, and the signing event, along with the certificate itself, is recorded in a public transparency log. Verification then checks both that the signature is mathematically valid and that the identity embedded in the certificate matches whatever identity a verification policy expects, rather than checking the signature against a long-term public key an operator has to separately manage.
sequenceDiagram
participant CI as CI Pipeline
participant ID as Identity Provider
participant CA as Short-Lived Cert Authority
participant Log as Transparency Log
participant Reg as Registry
CI->>ID: prove pipeline identity
ID-->>CI: identity token
CI->>CA: request short-lived cert with identity
CA-->>CI: signing certificate (minutes of validity)
CI->>CI: sign image digest with cert's key
CI->>Log: record signing event
CI->>Reg: push image + signature
The verification decision
At deployment time, verification checks the presented signature against the image’s actual content digest, confirming the signature is mathematically valid, and then checks the signer’s identity — whether that’s a specific public key fingerprint or a specific verified identity from a keyless certificate — against whatever policy the verifying system has been configured to trust. Only if both checks pass does the image proceed to deployment; a valid-looking signature from an untrusted or unexpected signer is, correctly, treated as a failure, since verifying the cryptographic math alone is not sufficient without also confirming the signer is who the policy actually expects.
Tracing an image’s journey from build through signing, storage, and eventual enforced verification before it is allowed to run.
Image Built
The container image is built as normal, producing content that will be identified by its own content digest.
Signing Performed
Either a protected long-lived private key or a freshly issued short-lived, identity-tied certificate is used to sign the image’s content digest.
Image and Signature Pushed
Both the image and its signature are pushed to the registry, associated with each other through the image’s content digest.
Deployment Requested
An operator or automated pipeline requests that the signed image be deployed to a target environment.
Verification Enforced
An admission or policy control point retrieves the image’s signature, verifies it against trusted keys or identities, and either allows or blocks the deployment based on the result.
Verified Image Runs
Only once verification succeeds does the image actually proceed to being scheduled and run in the target environment.
Why enforcement, not just signing, is what actually matters
It is worth being explicit about a subtlety that is easy to overlook: signing an image, by itself, provides no protection at all unless something downstream actually checks that signature and refuses to proceed when it is missing, invalid, or from an untrusted signer. An organization that signs every image but never configures its deployment pipeline to enforce verification has built the entire cryptographic apparatus for a security guarantee it is not actually receiving — the value of signing is realized entirely at the enforcement point, not at the signing step itself.
Chapter Five
EAdvantages, Disadvantages & Trade-offs
Image signing is a strong security investment, but it introduces real operational considerations that deserve honest treatment.
Advantages
- Provides strong, cryptographic proof of an image’s publisher and content integrity, independent of trusting the registry itself
- Keyless signing removes the significant operational burden of securely managing a long-lived private key over time
- Transparency logs create a publicly auditable record of signing events, aiding both accountability and incident investigation
- Integrates cleanly into automated CI/CD pipelines, requiring no manual, interactive step for routine, trusted builds
- Establishes a foundation other supply-chain security practices, like provenance attestation, can build directly on top of
Disadvantages
- Provides no guarantee about an image’s actual quality or safety — a signed image can still be vulnerable or misconfigured
- Traditional key-based signing carries real operational burden: secure key storage, rotation, and revocation planning
- Signing without corresponding enforcement at deployment time provides no actual security benefit despite the added process
- Keyless signing introduces a dependency on the availability of the identity provider and certificate authority infrastructure at signing time
- Retrofitting signing and enforcement onto an existing, already-large image catalog and pipeline can be a substantial undertaking
Choosing between traditional and keyless signing
The choice between traditional key-based signing and keyless signing generally comes down to an organization’s tolerance for the operational burden of long-term key management versus its readiness to depend on external identity and certificate infrastructure. Organizations with mature, existing key management practices (such as a hardware security module already in production use) may find traditional signing a natural fit; organizations prioritizing operational simplicity and automated CI/CD-native workflows frequently find keyless signing’s removal of long-term secret management a meaningful advantage, provided they are comfortable with the underlying trust model of short-lived, identity-verified certificates.
Treat image signing as one deliberate layer within a broader supply-chain security strategy, not a complete solution on its own — pairing it with vulnerability scanning, provenance attestation, and, critically, enforced verification at deployment time is what actually closes the loop from a cryptographic capability to a genuine security guarantee.
Chapter Six
FSecurity
Because image signing exists specifically to serve a security goal, this chapter looks at the specific threats it addresses and the threats it deliberately leaves to other controls.
The specific attack it defends against
Image signing directly defends against a supply chain attack scenario often called image substitution or tampering: an attacker who gains write access to a registry, intercepts network traffic, or otherwise manages to insert a malicious image in place of a legitimate one, hoping that unsuspecting downstream consumers will pull and run it as though it were genuine. Without signature verification, this kind of substitution can be nearly invisible to a consumer who has no independent way to confirm an image’s true origin. With enforced signature verification in place, a substituted image simply fails verification, since the attacker does not hold the legitimate publisher’s private key or verified signing identity, and the deployment is blocked before the malicious content ever runs.
Image signing is like a pharmacy checking a tamper-evident seal on a medication bottle before dispensing it, rather than simply trusting that whatever bottle is on the shelf must be genuine. The seal doesn’t verify the medication itself is effective or correctly formulated — that’s a separate quality-control process — but it does provide strong assurance that nobody has opened, altered, or substituted the contents since the manufacturer sealed it.
Where trust ultimately has to root somewhere
Even the strongest signature verification scheme has to root trust somewhere — either in a securely distributed public key, or in a trusted identity provider and certificate authority for keyless signing — and that root of trust becomes, by definition, the single most sensitive point in the entire system. A compromise of the signing key itself, or of the identity infrastructure a keyless scheme depends on, undermines every guarantee the signature system provides, which is why protecting that root of trust with commensurate rigor (hardware-backed key storage, strict access controls on identity provider configuration) matters as much as adopting signing in the first place.
Context
An organization had adopted image signing across its build pipelines but discovered, during a security review, that its production deployment tooling never actually checked signatures, meaning unsigned or invalidly signed images could still be deployed without any blocking check.
Decision
Deployment tooling for every production environment was updated to enforce signature verification as a hard gate, rejecting any image that lacked a valid signature from an explicitly trusted signer before allowing deployment to proceed.
Consequence
The organization’s existing signing investment finally translated into an actual, enforced security guarantee rather than an unused capability, at the cost of a short remediation period fixing a handful of legacy pipelines that had not previously produced signed images at all.
Confirming that signing and enforcement are genuinely working end-to-end requires watching specific, verifiable signals rather than assuming success.
What to watch at the enforcement point
The most important operational signal is the outcome of every verification check performed at deployment time — specifically, tracking both successful verifications and, just as importantly, any rejected deployment attempts due to a missing, invalid, or untrusted signature. A sudden spike in rejected deployments can indicate either a genuine attempted substitution worth investigating immediately, or, more commonly in practice, a build pipeline misconfiguration that has stopped producing valid signatures — both scenarios warrant prompt attention, but for very different reasons.
| Signal | What It Indicates | Recommended Response |
|---|---|---|
| Consistent successful verifications | Signing and enforcement pipeline functioning as intended | Routine monitoring, no action needed |
| Sudden spike in rejected deployments | Either a pipeline misconfiguration or a genuine substitution attempt | Immediate investigation to distinguish the two |
| Signature present but from unexpected signer | Possible unauthorized build source, or a legitimate new pipeline not yet trusted | Verify signer identity against expected sources before trusting |
| Transparency log entries with unexpected timing | Signing occurring outside expected build windows | Correlate against known, legitimate build activity |
Auditing coverage across an image catalog
Beyond watching real-time verification outcomes, periodically auditing what fraction of an organization’s actively deployed images are genuinely signed and covered by enforced verification policy — rather than assuming full coverage based on when a signing initiative was originally announced — catches images that were never brought into the signing process, or older images that predate its adoption and have simply never been revisited.
An organization midway through adopting signing, with enforcement enabled for some environments or image catalogs but not others, can develop a false sense of complete coverage if monitoring only reports on the portion already enforcing verification. Explicitly tracking and reporting on unenforced gaps, not just enforced successes, is necessary to see the true state of adoption.
Chapter Eight
HDesign Patterns & Anti-patterns
Recurring approaches that make image signing a genuinely effective, sustainable practice, and the recurring mistakes that leave it as unenforced theater.
Sign at Build Time, Enforce at Deploy Time
Integrating signing as an automatic, mandatory step within the CI/CD pipeline itself, paired with a non-bypassable enforcement check at every deployment target, so the two halves of the guarantee are never separated in practice.
Explicit Trusted-Signer Policy
Maintaining a clear, reviewed policy defining exactly which signers (keys or verified identities) are trusted for which environments, rather than implicitly trusting any validly formatted signature regardless of who produced it.
Layered Verification with Attestations
Combining signature verification with additional signed attestations — such as proof a required vulnerability scan was performed and passed — building a richer, more complete supply-chain trust picture than signature verification alone provides.
Signing Without Enforcement
Adopting signing across build pipelines while leaving deployment tooling unconfigured to actually check those signatures, producing a false sense of security with no real protective effect.
Trusting Any Valid Signature Regardless of Signer
Configuring verification to accept any cryptographically valid signature without checking the signer’s identity against an explicit trust policy, which would allow a validly self-signed but entirely unauthorized image to pass verification.
Pattern in practice: staged trust rollout
Organizations introducing signature enforcement into an existing, previously unsigned environment often stage the rollout deliberately — first running enforcement in a reporting-only mode that logs would-be rejections without actually blocking deployments, giving teams visibility into gaps before the policy becomes a genuine, blocking gate.
Concrete, practical guidance for rolling out image signing in a way that produces a genuine, lasting security benefit.
Enforce verification, not just produce signatures
Treat enforcement at the deployment gate as the actual deliverable of a signing initiative, with signing itself as a necessary but insufficient prerequisite step.
Define an explicit, reviewed trust policy
Maintain a clear record of exactly which signers are trusted for which environments, reviewed periodically rather than left as an implicit, undocumented default.
Roll out enforcement in reporting mode first
Introduce a non-blocking observation period before making signature verification a hard, blocking gate, surfacing gaps in existing pipelines before they become production incidents.
Treating a signed image as automatically safe
Conflating signature verification with a guarantee of security quality; a signed image still needs separate vulnerability scanning and configuration review.
Leaving legacy or third-party images entirely outside the policy
Excluding older, internally built images or externally sourced third-party images from signing and verification requirements without a deliberate, documented decision to do so.
Underestimating the operational cost of traditional key management
Adopting long-lived key-based signing without a concrete plan for secure storage, rotation, and revocation, treating key management as an afterthought rather than a core part of the signing rollout.
Chapter Ten
JReal-World & Industry Examples
Image signing has moved from a niche, advanced practice to an increasingly expected baseline across security-conscious container ecosystems.
Sigstore Adoption Across Major Projects
The Sigstore project’s keyless signing model, including Cosign, has seen rapid adoption across many prominent open-source projects specifically because it removes the key-management burden that previously made signing impractical for volunteer-maintained software.
Compliance-Driven Signing Mandates
Organizations in regulated sectors increasingly face explicit compliance expectations around software supply chain integrity, with signed and verified container images serving as concrete, auditable evidence of provenance controls.
Native Policy Controller Integration
Modern Kubernetes-native admission and policy controllers commonly offer built-in support for enforcing signature verification directly as part of the pod admission process, integrating signing enforcement natively into the orchestration layer.
Signed Official Vendor Images
Software vendors distributing container images increasingly sign their official releases as a standard practice, giving downstream customers a concrete, verifiable way to confirm they are running genuine, untampered vendor-published software.
Chapter Eleven
KFrequently Asked Questions
Chapter Twelve
LSummary and Key Takeaways
Image signing turns an implicit, unverifiable trust assumption into a concrete, cryptographically enforceable guarantee — provided that guarantee is actually enforced.
Key Takeaways
- A container image signature proves authenticity and integrity — who published it and that its content is unchanged — but says nothing about the image’s actual security quality or safety.
- Notary v2 and Cosign represent two major modern approaches, differing primarily in registry integration philosophy and, for Cosign, offering a keyless signing model built on short-lived, identity-verified certificates.
- Signatures are applied over an image’s content digest, the same identifier used throughout content-addressable registry storage, making signing efficient regardless of image size.
- Keyless signing removes the significant operational burden of long-term private key management by substituting short-lived certificates tied to verified identities, recorded in a public transparency log.
- A signature provides no actual security benefit unless it is genuinely enforced at deployment time — signing without enforcement is a common and consequential gap that leaves the underlying threat entirely unaddressed.
- Effective adoption pairs enforced signature verification with an explicit trusted-signer policy and complementary practices like vulnerability scanning, treating signing as one essential layer within a broader supply-chain security strategy rather than a complete solution on its own.