github.com/jogo/docker@v1.7.0-rc1/docs/sources/articles/certificates.md (about) 1 page_title: Using certificates for repository client verification 2 page_description: How to set up and use certificates with a registry to verify access 3 page_keywords: Usage, registry, repository, client, root, certificate, docker, apache, ssl, tls, documentation, examples, articles, tutorials 4 5 # Using certificates for repository client verification 6 7 In [Running Docker with HTTPS](/articles/https), you learned that, by default, 8 Docker runs via a non-networked Unix socket and TLS must be enabled in order 9 to have the Docker client and the daemon communicate securely over HTTPS. 10 11 Now, you will see how to allow the Docker registry (i.e., *a server*) to 12 verify that the Docker daemon (i.e., *a client*) has the right to access the 13 images being hosted with *certificate-based client-server authentication*. 14 15 We will show you how to install a Certificate Authority (CA) root certificate 16 for the registry and how to set the client TLS certificate for verification. 17 18 ## Understanding the configuration 19 20 A custom certificate is configured by creating a directory under 21 `/etc/docker/certs.d` using the same name as the registry's hostname (e.g., 22 `localhost`). All `*.crt` files are added to this directory as CA roots. 23 24 > **Note:** 25 > In the absence of any root certificate authorities, Docker 26 > will use the system default (i.e., host's root CA set). 27 28 The presence of one or more `<filename>.key/cert` pairs indicates to Docker 29 that there are custom certificates required for access to the desired 30 repository. 31 32 > **Note:** 33 > If there are multiple certificates, each will be tried in alphabetical 34 > order. If there is an authentication error (e.g., 403, 404, 5xx, etc.), Docker 35 > will continue to try with the next certificate. 36 37 Our example is set up like this: 38 39 /etc/docker/certs.d/ <-- Certificate directory 40 └── localhost <-- Hostname 41 ├── client.cert <-- Client certificate 42 ├── client.key <-- Client key 43 └── localhost.crt <-- Registry certificate 44 45 ## Creating the client certificates 46 47 You will use OpenSSL's `genrsa` and `req` commands to first generate an RSA 48 key and then use the key to create the certificate. 49 50 $ openssl genrsa -out client.key 1024 51 $ openssl req -new -x509 -text -key client.key -out client.cert 52 53 > **Warning:**: 54 > Using TLS and managing a CA is an advanced topic. 55 > You should be familiar with OpenSSL, x509, and TLS before 56 > attempting to use them in production. 57 58 > **Warning:** 59 > These TLS commands will only generate a working set of certificates on Linux. 60 > The version of OpenSSL in Mac OS X is incompatible with the type of 61 > certificate Docker requires. 62 63 ## Testing the verification setup 64 65 You can test this setup by using Apache to host a Docker registry. 66 For this purpose, you can copy a registry tree (containing images) inside 67 the Apache root. 68 69 > **Note:** 70 > You can find such an example [here]( 71 > http://people.gnome.org/~alexl/v1.tar.gz) - which contains the busybox image. 72 73 Once you set up the registry, you can use the following Apache configuration 74 to implement certificate-based protection. 75 76 # This must be in the root context, otherwise it causes a re-negotiation 77 # which is not supported by the TLS implementation in go 78 SSLVerifyClient optional_no_ca 79 80 <Location /v1> 81 Action cert-protected /cgi-bin/cert.cgi 82 SetHandler cert-protected 83 84 Header set x-docker-registry-version "0.6.2" 85 SetEnvIf Host (.*) custom_host=$1 86 Header set X-Docker-Endpoints "%{custom_host}e" 87 </Location> 88 89 Save the above content as `/etc/httpd/conf.d/registry.conf`, and 90 continue with creating a `cert.cgi` file under `/var/www/cgi-bin/`. 91 92 #!/bin/bash 93 if [ "$HTTPS" != "on" ]; then 94 echo "Status: 403 Not using SSL" 95 echo "x-docker-registry-version: 0.6.2" 96 echo 97 exit 0 98 fi 99 if [ "$SSL_CLIENT_VERIFY" == "NONE" ]; then 100 echo "Status: 403 Client certificate invalid" 101 echo "x-docker-registry-version: 0.6.2" 102 echo 103 exit 0 104 fi 105 echo "Content-length: $(stat --printf='%s' $PATH_TRANSLATED)" 106 echo "x-docker-registry-version: 0.6.2" 107 echo "X-Docker-Endpoints: $SERVER_NAME" 108 echo "X-Docker-Size: 0" 109 echo 110 111 cat $PATH_TRANSLATED 112 113 This CGI script will ensure that all requests to `/v1` *without* a valid 114 certificate will be returned with a `403` (i.e., HTTP forbidden) error.