## 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)