Registry trust — pulling from who you think you are · Docker & Containers

When you docker pull nginx, six things happen in order:

registry-1.docker.io is resolved to an address via DNS.
A TLS connection is established.
The certificate chain is validated — trusted issuer, hostname in the SAN, not expired.
Authentication, if required: a token is obtained and presented.
The manifest is requested.
Each layer blob is downloaded.

Each step authenticates something different, and the single most useful thing to internalise is that steps 2 and 3 authenticate the server, not the image. A perfectly valid certificate on a registry that is serving a backdoored image passes every TLS check there is.

What each control actually protects

Step	Protected by	Against
DNS resolution	Nothing, on its own	—
TLS handshake	Certificate validation	Talking to the wrong server
Authentication	Credentials and scoped tokens	Unauthorised push and pull
Manifest fetch	The digest, if you pinned one	Getting a different artefact
Layer download	Content addressing	Corrupted or substituted bytes
The image itself	A signature	An artefact your publisher did not produce

DNS is worth a line of its own. Cache poisoning, a compromised resolver or a BGP hijack can point your pull at an attacker’s server. That is a real attack and TLS is the reason it usually fails: the attacker reaches step 2 and cannot produce a certificate your daemon accepts for that hostname.

Usually. It fails unless somebody has widened the trust store, added the host to insecure-registries, or the attacker has obtained a certificate a public CA will issue for a name they control.

Diagnosing a trust failure

The errors look similar in a pipeline log and mean very different things. Work out which link broke before you change anything.

Read-only / Safex509: certificate signed by unknown authority— Step 3. The chain does not lead to a CA the daemon trusts.

$ docker pull registry.example.com/myorg/myapp:1.4.0

Error response from daemon: Get "https://registry.example.com/v2/": x509: certificate signed by unknown authority

Illustrative output

That is a private CA the host does not know about, or an intercepting proxy. It is not a network problem and it is not the registry being down.

Read-only / Safex509: certificate is valid for ...— Step 3 again, but a different cause: the certificate is trusted and does not cover this hostname.

$ docker pull registry.example.com/myorg/myapp:1.4.0

Error response from daemon: Get "https://registry.example.com/v2/": x509: certificate is valid for registry.internal.example.com, not registry.example.com

Illustrative output

Usually a load balancer terminating TLS with the wrong certificate, or a CNAME added without reissuing. Occasionally it is the interesting case.

Read-only / Safesee the certificate the registry is actually serving— Bypasses Docker entirely. Shows the issuer, the subject alternative names and the validity window.

REGISTRY=registry.example.com

openssl s_client -connect "${REGISTRY}:443" -servername "$REGISTRY" </dev/null 2>/dev/null \
| openssl x509 -noout -issuer -subject -dates -ext subjectAltName

issuer=C=US, O=Let's Encrypt, CN=R11
subject=CN=registry.example.com
notBefore=Jul 14 08:11:02 2026 GMT
notAfter=Oct 12 08:11:01 2026 GMT
X509v3 Subject Alternative Name:
  DNS:registry.example.com

Illustrative output

The -servername flag matters: a registry behind a shared load balancer selects its certificate by SNI, and omitting it gets you the default certificate rather than the one your daemon will see.

Read-only / Safeconfirm where the name resolves— Step 1. Compare against what you expect, and against what another network sees.

REGISTRY=registry.example.com

getent hosts "$REGISTRY"
docker run --rm --network host busybox nslookup "$REGISTRY" 2>/dev/null | tail -5

203.0.113.40    registry.example.com

Illustrative output

A registry that resolves differently inside a container than on the host is the signature of a split-horizon DNS setup or a container DNS override, and it produces failures that look like intermittent registry outages.

Trusting a private CA

The correct fix for a certificate your daemon does not recognise is to teach it the CA. The daemon looks for CA material in a directory named for the registry — the documentation gives the layout directly: “a copy of its CA certificate is placed on the Docker host at /etc/docker/certs.d/myregistry:5000/ca.crt.”

Configuration changetrust a private CA for one registry— Scoped to one registry hostname. Verification stays on everywhere, including for this host.

REGISTRY=registry.example.com

sudo mkdir -p "/etc/docker/certs.d/${REGISTRY}"
sudo cp internal-ca.crt "/etc/docker/certs.d/${REGISTRY}/ca.crt"
sudo chmod 0644 "/etc/docker/certs.d/${REGISTRY}/ca.crt"

docker pull "${REGISTRY}/myorg/myapp:1.4.0"

If the registry listens on a non-standard port, the directory name includes the port, exactly as in the documented example.

insecure-registries is not 'accept this certificate'

The tempting alternative:

{
  "insecure-registries": ["registry.example.com"]
}

Per the documentation, “an insecure registry is either not using TLS (i.e., listening on plain text HTTP), or is using TLS with a CA certificate not known by the Docker daemon”. Adding a host to this list tells the daemon to accept both of those conditions for that host — daemon-wide, for every user, for every image, until somebody removes the line.

Anyone who can position themselves on that network path can now serve you images, and nothing in any log will look unusual. The entry outlives the incident that motivated it, because it makes the error go away and nothing ever fails afterwards to remind anyone it is there.

Note that Docker already treats local registries as insecure by default, so a registry on localhost does not need this and is not evidence that the flag is normal practice.

Audit for it:

docker info --format '{{json .RegistryConfig.InsecureRegistryCIDRs}}'
grep -R 'insecure-registries' /etc/docker/ 2>/dev/null || echo 'none configured'

Mirrors and the trust they inherit

A registry-mirrors entry redirects Docker Hub pulls through a server you nominate. That server now sees every pull you make and is in a position to answer them.

Read-only / Safewhat your daemon has been told to trust— Run this on any host before you reason about where its images come from. It is not visible in any image reference.

docker info --format 'mirrors: {{.RegistryConfig.Mirrors}}'

mirrors: [https://hub-cache.example.com/]

Illustrative output

The mirror is a genuine trust dependency: an operator of the mirror can serve different content for a tag, and nothing in the pull command or the resulting docker images output would show it.

And here is the payoff of everything in this part of the course: pin by digest and that stops being true. Content addressing means the daemon verifies the bytes it received against the digest it asked for. A hostile mirror can refuse to serve you, and it cannot substitute. Trust in the transport becomes replaceable by trust in the content, which is a much smaller thing to have to defend.

Where verification actually happens

Steps 2 and 3 are handled by the Go TLS stack in the daemon, using the system trust store plus anything in /etc/docker/certs.d/. That is a statement about the connection.

Step 6 is different in kind. Each blob is requested by digest, and the daemon hashes the bytes as they arrive and compares. A mismatch aborts the pull. This check runs regardless of TLS, regardless of authentication, and regardless of whether the server was a mirror, a cache or the origin.

The consequence is worth stating carefully because it is the whole argument for digest pinning: for an image referenced by digest, transport integrity is not load-bearing. You would prefer TLS for confidentiality and for not wasting bandwidth on garbage, but a substitution attack fails at the hash comparison rather than at the certificate check.

For an image referenced by tag, this does not hold. Step 5 asks the server which digest the tag names, and the server’s answer is authoritative. Everything downstream faithfully verifies bytes against a digest an untrusted party chose. That is the precise, mechanical reason a tag reference cannot be part of a trust argument.

The remaining gap, in both cases, is that content addressing tells you the bytes are the bytes somebody published. It does not tell you who. That is what a signature adds, and it is why the chain is digest → signature → identity policy rather than stopping at TLS.

Docker Content Trust is going away

Older guidance recommends DOCKER_CONTENT_TRUST=1, which enables Notary v1 signature verification at pull time.

That mechanism is being retired. The documentation states: “Docker Content Trust (DCT) is being retired. The Notary v1 service at notary.docker.io will shut down on December 8, 2026.”

If you have DOCKER_CONTENT_TRUST=1 set anywhere — a CI image, a profile script, a systemd unit — find it now rather than on the day it starts failing:

Read-only / Safefind Content Trust settings— Checks the current environment and the usual places it gets set persistently.

printenv DOCKER_CONTENT_TRUST || echo 'not set in this shell'
grep -R 'DOCKER_CONTENT_TRUST' /etc/environment /etc/profile.d/ /etc/systemd/system/ 2>/dev/null \
|| echo 'not set persistently'

not set in this shell
not set persistently

The replacement is Cosign signatures verified at deploy time, covered in the signing lesson. There is no drop-in daemon-level equivalent — enforcement moves into your admission controller or your deploy tooling, which is a real change in where the control lives.

Public registries and the names you type

Docker Hub is a public registry. Anyone can push to it. The library/* namespace holds Docker Official Images, reviewed by Docker; everything else is whoever registered the name.

The risks are less about cryptography than about typing:

Typosquatting. A name one character away from a popular image, published by somebody else, waiting for a Dockerfile typo.
The implicit library/ prefix. docker pull alpine is an official image. docker pull someuser/alpine is not, and the two differ by an easily overlooked prefix in a review diff.
Namespace transfer. A repository that was trustworthy for years can change hands. Nothing about the reference changes.
Abandonment. Popularity is not maintenance, and a download count is a measure of the past.

None of those are defeated by TLS, by authentication, or by pulling from a mirror. They are defeated by pinning a digest you evaluated and by verifying a signature from a publisher you named.

Vendor registries

Cloud registries — AWS ECR, Google Artifact Registry, Azure Container Registry — authenticate through the cloud provider’s IAM rather than through a registry-local account.

Configuration changeECR login— The token is short-lived. The IAM identity behind it is what actually grants access, and that is the thing to audit.

REGION=us-east-1
ACCOUNT=123456789012
REGISTRY="${ACCOUNT}.dkr.ecr.${REGION}.amazonaws.com"

aws ecr get-login-password --region "$REGION" \
| docker login --username AWS --password-stdin "$REGISTRY"

Login Succeeded

Illustrative output

This is a genuine improvement — the credential on the host is an instance role rather than a password, and it rotates automatically. It also moves the interesting question elsewhere: the audit is now of IAM policy, not of a registry user list, and the common finding is a role with pull permission scoped far more broadly than anybody intended.

What if the registry you trust serves you a malicious image?

This is the case that separates transport trust from content trust, so work through it precisely.

TLS does not help. The connection was to the correct server, with a valid certificate. Every check passed.

Authentication does not help. You authenticated correctly. So did whoever pushed the image.

A tag reference does not help. You asked which digest the tag names; the registry answered; you verified the bytes against that answer. The verification succeeded and verified the wrong thing.

A digest pin helps if the digest predates the compromise. The registry cannot serve different bytes under a digest you already recorded. It can delete them, which is an outage rather than a substitution.

A signature helps unconditionally, as long as the signing identity was not also compromised. The image the attacker pushed is not signed by your publishing pipeline, so a verification constrained to that identity rejects it — regardless of what the registry says.

This is why the controls stack in this order and why none of them is redundant: TLS gets you to the right server, authentication controls who can write, digests fix the artefact, and signatures attach it to a publisher. Remove any one and there is a class of attack that walks straight through.

The practical action if you suspect it has happened: enumerate every digest currently deployed, check each against the digests your build system says it produced, and verify signatures on all of them. Digest pinning is what makes that enumeration possible at all — without it, the deployed set is “whatever those tags pointed at when each host last pulled”, which is not knowable after the fact.

Fully qualify registry hostnames in anything that is not an interactive shell, so a reference means one thing everywhere.
**Trust private CAs through /etc/docker/certs.d/**, never through insecure-registries.
**Audit every host for insecure-registries and unexpected registry-mirrors** — both are invisible in the image reference.
Pin production references by digest, which makes transport integrity non-load-bearing.
Verify a signature from a named publisher identity before deploying, since that is the only control that survives a compromised registry.
**Retire DOCKER_CONTENT_TRUST usage** ahead of the Notary v1 shutdown rather than after it.

Why this matters

Registry trust is a chain, and the useful skill is knowing which link each control covers. TLS is the one people cite and it protects exactly one thing: that you reached the server you named. It says nothing about whether that server is honest, whether the tag you asked for still means what it meant last week, or whether the image was built by anyone you have heard of.

The diagnostic value is immediate — an x509 error, a 401, a 429 and a digest mismatch are four different incidents with four different responses, and treating them as “the registry is broken” wastes the first hour of each.

The design value is larger. Once you can see that content addressing verifies bytes independently of the transport, the whole architecture simplifies: you stop trying to make the network trustworthy and start making the artefact self-describing. That is the difference between a supply chain you defend and one you hope about.

What each control actually protects

Diagnosing a trust failure

Trusting a private CA

Mirrors and the trust they inherit

Docker Content Trust is going away

Public registries and the names you type

Vendor registries

Knowledge check