moby/docs/articles/certificates.md

Using certificates for repository client verification

In Running Docker with HTTPS, 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.

Now, you will see how to allow the Docker registry (i.e., a server) to verify that the Docker daemon (i.e., a client) has the right to access the images being hosted with certificate-based client-server authentication.

We will show you how to install a Certificate Authority (CA) root certificate for the registry and how to set the client TLS certificate for verification.

Understanding 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 (e.g., localhost). All *.crt files are added to this directory as CA roots.

Note: In the absence of any root certificate authorities, Docker will use the system default (i.e., host's root CA set).

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 there are multiple certificates, each will be tried in alphabetical order. If there is an authentication error (e.g., 403, 404, 5xx, etc.), Docker will continue to try with the next certificate.

Our example is set up like this:

/etc/docker/certs.d/        <-- Certificate directory
└── localhost               <-- Hostname
   ├── client.cert          <-- Client certificate
   ├── client.key           <-- Client key
   └── localhost.crt        <-- Registry certificate

Creating the client certificates

You will use OpenSSL's genrsa and req commands to first generate an RSA key 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.cert

Warning:: Using TLS and managing a CA is an advanced topic. You should be familiar with OpenSSL, x509, and TLS before attempting to use them in production.

Warning: These TLS commands will only generate a working set of certificates on Linux. The version of OpenSSL in Mac OS X is incompatible with the type of certificate Docker requires.

Testing the verification setup

You can test this setup by using Apache to host a Docker registry. For this purpose, you can copy a registry tree (containing images) inside the Apache root.

Note: You can find such an example here - which contains the busybox image.

Once you set up the registry, you can use the following Apache configuration to implement certificate-based protection.

# This must be in the root context, otherwise it causes a re-negotiation
# which is not supported by the TLS implementation in go
SSLVerifyClient optional_no_ca

<Location /v1>
Action cert-protected /cgi-bin/cert.cgi
SetHandler cert-protected

Header set x-docker-registry-version "0.6.2"
SetEnvIf Host (.*) custom_host=$1
Header set X-Docker-Endpoints "%{custom_host}e"
</Location>

Save the above content as /etc/httpd/conf.d/registry.conf, and continue with creating a cert.cgi file under /var/www/cgi-bin/.

#!/bin/bash
if [ "$HTTPS" != "on" ]; then
    echo "Status: 403 Not using SSL"
    echo "x-docker-registry-version: 0.6.2"
    echo
    exit 0
fi
if [ "$SSL_CLIENT_VERIFY" == "NONE" ]; then
    echo "Status: 403 Client certificate invalid"
    echo "x-docker-registry-version: 0.6.2"
    echo
    exit 0
fi
echo "Content-length: $(stat --printf='%s' $PATH_TRANSLATED)"
echo "x-docker-registry-version: 0.6.2"
echo "X-Docker-Endpoints: $SERVER_NAME"
echo "X-Docker-Size: 0"
echo

cat $PATH_TRANSLATED

This CGI script will ensure that all requests to /v1 without a valid certificate will be returned with a 403 (i.e., HTTP forbidden) error.