Table of contents
InRunning Docker with HTTPS, you learned that, by default,Docker runs via a non-networked Unix socket and TLS must be enabled in orderto have the Docker client and the daemon communicate securely over HTTPS. TLS ensures authenticity of the registry endpoint and that traffic to/from registry is encrypted.
This article demonstrates how to ensure the traffic between the Docker registryserver and the Docker daemon (a client of the registry server) is encrypted andproperly authenticated using certificate-based client-server authentication.
We show you how to install a Certificate Authority (CA) root certificatefor the registry and how to set the client TLS certificate for verification.
A custom certificate is configured by creating a directory under/etc/docker/certs.d using the same name as the registry's hostname, such aslocalhost. All *.crt files are added to this directory as CA roots.
Note
On Linux any root certificates authorities are merged with the system defaults,including the host's root CA set. If you are running Docker on Windows Server,or Docker Desktop for Windows with Windows containers, the system defaultcertificates are only used when no custom root certificates are configured.
The presence of one or more <filename>.key/cert pairs indicates to Dockerthat there are custom certificates required for access to the desiredrepository.
Note
If multiple certificates exist, each is tried in alphabeticalorder. If there is a 4xx-level or 5xx-level authentication error, Dockercontinues to try with the next certificate.
The following illustrates a configuration with custom certificates:
/etc/docker/certs.d/ <-- Certificate directory └── localhost:5000 <-- Hostname:port ├── client.cert <-- Client certificate ├── client.key <-- Client key └── ca.crt <-- Root CA that signed the registry certificate, in PEMThe preceding example is operating-system specific and is for illustrativepurposes only. You should consult your operating system documentation forcreating an os-provided bundled certificate chain.
Create the client certificates
Use OpenSSL's genrsa and req commands to first generate an RSAkey and then use the key to create the certificate.
$ openssl genrsa -out client.key 4096$ openssl req -new -x509 -text -key client.key -out client.certNote
These TLS commands only generate a working set of certificates on Linux.The version of OpenSSL in macOS is incompatible with the type ofcertificate Docker requires.
The Docker daemon interprets .crt files as CA certificates and .cert filesas client certificates. If a CA certificate is accidentally given the extension.cert instead of the correct .crt extension, the Docker daemon logs thefollowing error message:
Missing key KEY_NAME for client certificate CERT_NAME. CA certificates should use the extension .crt.If the Docker registry is accessed without a port number, do not add the port to the directory name. The following shows the configuration for a registry on default port 443 which is accessed with docker login my-https.registry.example.com:
/etc/docker/certs.d/ └── my-https.registry.example.com <-- Hostname without port ├── client.cert ├── client.key └── ca.crt