path: root/devdocs/docker/engine%2Fsecurity%2Fcertificates%2Findex.html

<h1>Verify repository client with certificates</h1>

<p>In <a href="../protect-access/index">Running Docker with HTTPS</a>, you learned that, by default, Docker runs via a non-networked Unix socket and TLS must be enabled in order to 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.</p> <p>This article demonstrates how to ensure the traffic between the Docker registry server and the Docker daemon (a client of the registry server) is encrypted and properly authenticated using <em>certificate-based client-server authentication</em>.</p> <p>We show you how to install a Certificate Authority (CA) root certificate for the registry and how to set the client TLS certificate for verification.</p> <h2 id="understand-the-configuration">Understand the configuration</h2> <p>A custom certificate is configured by creating a directory under <code class="language-plaintext highlighter-rouge">/etc/docker/certs.d</code> using the same name as the registry’s hostname, such as <code class="language-plaintext highlighter-rouge">localhost</code>. All <code class="language-plaintext highlighter-rouge">*.crt</code> files are added to this directory as CA roots.</p> <blockquote> <p><strong>Note</strong></p> <p>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.</p> </blockquote> <p>The presence of one or more <code class="language-plaintext highlighter-rouge">&lt;filename&gt;.key/cert</code> pairs indicates to Docker that there are custom certificates required for access to the desired repository.</p> <blockquote> <p><strong>Note</strong>: 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.</p> </blockquote> <p>The following illustrates a configuration with custom certificates:</p> <div class="highlight"><pre class="highlight" data-language="">    /etc/docker/certs.d/        &lt;-- Certificate directory
    └── localhost:5000          &lt;-- Hostname:port
       ├── client.cert          &lt;-- Client certificate
       ├── client.key           &lt;-- Client key
       └── ca.crt               &lt;-- Certificate authority that signed
                                    the registry certificate
</pre></div> <p>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.</p> <h2 id="create-the-client-certificates">Create the client certificates</h2> <p>Use OpenSSL’s <code class="language-plaintext highlighter-rouge">genrsa</code> and <code class="language-plaintext highlighter-rouge">req</code> commands to first generate an RSA key and then use the key to create the certificate.</p> <div class="highlight"><pre class="highlight" data-language="">$ openssl genrsa -out client.key 4096
$ openssl req -new -x509 -text -key client.key -out client.cert
</pre></div> <blockquote> <p><strong>Note</strong>: 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.</p> </blockquote> <h2 id="troubleshooting-tips">Troubleshooting tips</h2> <p>The Docker daemon interprets <code class="language-plaintext highlighter-rouge">.crt</code> files as CA certificates and <code class="language-plaintext highlighter-rouge">.cert</code> files as client certificates. If a CA certificate is accidentally given the extension <code class="language-plaintext highlighter-rouge">.cert</code> instead of the correct <code class="language-plaintext highlighter-rouge">.crt</code> extension, the Docker daemon logs the following error message:</p> <div class="highlight"><pre class="highlight" data-language="">Missing key KEY_NAME for client certificate CERT_NAME. CA certificates should use the extension .crt.
</pre></div> <p>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 <code class="language-plaintext highlighter-rouge">docker login my-https.registry.example.com</code>:</p> <div class="highlight"><pre class="highlight" data-language="">    /etc/docker/certs.d/
    └── my-https.registry.example.com          &lt;-- Hostname without port
       ├── client.cert
       ├── client.key
       └── ca.crt
</pre></div> <h2 id="related-information">Related information</h2> <ul> <li><a href="../trust/index">Use trusted images</a></li> <li><a href="../protect-access/index">Protect the Docker daemon socket</a></li> </ul> 
<p><a href="https://docs.docker.com/search/?q=Usage">Usage</a>, <a href="https://docs.docker.com/search/?q=registry">registry</a>, <a href="https://docs.docker.com/search/?q=repository">repository</a>, <a href="https://docs.docker.com/search/?q=client">client</a>, <a href="https://docs.docker.com/search/?q=root">root</a>, <a href="https://docs.docker.com/search/?q=certificate">certificate</a>, <a href="https://docs.docker.com/search/?q=docker">docker</a>, <a href="https://docs.docker.com/search/?q=apache">apache</a>, <a href="https://docs.docker.com/search/?q=ssl">ssl</a>, <a href="https://docs.docker.com/search/?q=tls">tls</a>, <a href="https://docs.docker.com/search/?q=documentation">documentation</a>, <a href="https://docs.docker.com/search/?q=examples">examples</a>, <a href="https://docs.docker.com/search/?q=articles">articles</a>, <a href="https://docs.docker.com/search/?q=tutorials">tutorials</a></p>
<div class="_attribution">
  <p class="_attribution-p">
    &copy; 2019 Docker, Inc.<br>Licensed under the Apache License, Version 2.0.<br>Docker and the Docker logo are trademarks or registered trademarks of Docker, Inc. in the United States and/or other countries.<br>Docker, Inc. and other parties may also have trademark rights in other terms used herein.<br>
    <a href="https://docs.docker.com/engine/security/certificates/" class="_attribution-link">https://docs.docker.com/engine/security/certificates/</a>
  </p>
</div>