Name Docker registry certificate files by their role

Bottom line: Review certificate roles and the registry directory before replacing trust material to clear an error. Keep the daemon’s registry-client identity separate from the registry’s CA trust and from the application running inside a container.

Source fact: documented behavior

The Verify repository client with certificates documentation is the primary reference.

For native Linux Engine, the guide places registry-specific certificate directories under /etc/docker/certs.d/; a registry accessed without a port uses a directory name without the port. Docker interprets .crt files as CA certificates and .cert files as client certificates, with the documented client configuration including a matching .key file. Giving a CA certificate the .cert extension can produce the documented missing-client-key error instead of making it a CA root.

What the source does not establish

This article addresses native Linux registry certificate layout and role selection, not certificate issuance or a compatibility guarantee. It excludes the different rootless, Desktop and Windows roots documented on the page. It does not approve an untrusted CA or recommend bypassing certificate verification.

Applicability questions

• Which exact registry address does the native Linux daemon access?
• Which files are CA roots and which represent a client identity?
• Does each intended client certificate have its approved matching key?
• Does the diagnostic refer to naming, trust, identity or registry authorization?

DSE recommendation: review a certificate-role map

DSE recommends a sanitized directory map naming the registry address and each file’s intended role. Obtain the expected CA and client identity from the approved certificate process. Record certificate identifiers and controlled key references without copying private material into the troubleshooting ticket.

Check the actual daemon deployment before using the native Linux path. Keep a rootless or Desktop installation in its separately documented branch. Reconcile the address the client uses with the directory name, including whether the invocation includes a port. Do not invent a port suffix from a remembered default.

Review a missing-key error against the role map before generating another key. Check whether a CA file was mislabeled as a client certificate and whether the intended client pair is present. Have the credential owner resolve a true pairing problem rather than renaming files until the error disappears.

Keep authentication and repository permission separate. Define the intended permitted operation and an excluded operation with the registry owner, then use the approved test identity. Retain the diagnostic and the exact reviewed layout with the result. Avoid adding unrelated roots or weakening verification to obtain a convenient successful login.

Verification and evidence

Proposed verification, not performed: use an isolated native Linux daemon and an approved test registry with disposable issued credentials. Inspect the configured directory and roles, then exercise the agreed harmless registry operation through the normal client route. Keep private keys and reusable credentials outside captured output.

If a mislabeled-file case is useful, reproduce it only in the disposable configuration and compare its actual error with the documented diagnostic. Restore the approved layout before the final authentication and permission checks. Retain the registry address, certificate identifiers, redacted map and observations without treating file naming alone as proof of endpoint trust.

Official references

• Verify repository client with certificates — Docker Docs.

Source review completed October 29, 2026. Recheck the official documentation and deployment-specific applicability before a production change.