Home • Explore • Blog • CI
☰



docker
2nd chunk of `content/manuals/engine/security/certificates.md`
05d6472e42150e67343587952fb249f0296e10ac407dc2210000000100000bbd
## Understand the configuration

A custom certificate is configured by creating a directory under
`/etc/docker/certs.d` using the same name as the registry's hostname, such as
`localhost`. 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 default
> certificates are only used when no custom root certificates are configured.

The presence of one or more `<filename>.key/cert` pairs indicates to Docker
that there are custom certificates required for access to the desired
repository.

> [!NOTE]
>
> If multiple certificates exist, each is tried in alphabetical
> order. If there is a 4xx-level or 5xx-level authentication error, Docker
> continues to try with the next certificate.

The following illustrates a configuration with custom certificates:

```text
    /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 PEM
```

The preceding example is operating-system specific and is for illustrative
purposes only. You should consult your operating system documentation for
creating an os-provided bundled certificate chain.


## Create the client certificates

Use OpenSSL's `genrsa` and `req` commands to first generate an RSA
key and then use the key to create the certificate.   

```console
$ openssl genrsa -out client.key 4096
$ openssl req -new -x509 -text -key client.key -out client.cert
```

> [!NOTE]
>
> These TLS commands only generate a working set of certificates on Linux.
> The version of OpenSSL in macOS is incompatible with the type of
> certificate Docker requires.

## Troubleshooting tips

The Docker daemon interprets `.crt` files as CA certificates and `.cert` files
as client certificates. If a CA certificate is accidentally given the extension
`.cert` instead of the correct `.crt` extension, the Docker daemon logs the
following error message:

```text
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`:

```text
    /etc/docker/certs.d/
    └── my-https.registry.example.com          <-- Hostname without port
       ├── client.cert
       ├── client.key
       └── ca.crt
```

## Related information

* [Use trusted images](trust/_index.md)
* [Protect the Docker daemon socket](protect-access.md)
Title: Configuration, Certificate Creation, and Troubleshooting
Summary
This section explains how to configure custom certificates for Docker registry authentication by placing `.crt` files as CA roots and `<filename>.key/cert` pairs for client authentication in the `/etc/docker/certs.d` directory. It provides an example directory structure and notes that Linux systems merge custom root certificates with system defaults. It also details how to create client certificates using OpenSSL and offers troubleshooting tips, including correcting file extensions and handling registries accessed without a port number. It references related documentation on trusted images and protecting the Docker daemon socket.