diff --git a/docs/sources/articles/certificates.md b/docs/sources/articles/certificates.md index 3772a7bc57..90d3f1b356 100644 --- a/docs/sources/articles/certificates.md +++ b/docs/sources/articles/certificates.md @@ -1,44 +1,80 @@ page_title: Using certificates for repository client verification -page_description: How to set up per-repository client certificates -page_keywords: Usage, repository, certificate, root, docker, documentation, examples +page_description: How to set up and use certificates with a registry to verify access +page_keywords: Usage, registry, repository, client, root, certificate, docker, apache, ssl, tls, documentation, examples, articles, tutorials # Using certificates for repository client verification -This lets you specify custom client TLS certificates and CA root for a -specific registry hostname. Docker will then verify the registry -against the CA and present the client cert when talking to that -registry. This allows the registry to verify that the client has a -proper key, indicating that the client is allowed to access the -images. +In [Running Docker with HTTPS](/articles/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. -A custom cert is configured by creating a directory in -`/etc/docker/certs.d` with the same name as the registry hostname. Inside -this directory all .crt files are added as CA Roots (if none exists, -the system default is used) and pair of files `$filename.key` and -`$filename.cert` indicate a custom certificate to present to the -registry. +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*. -If there are multiple certificates each one will be tried in -alphabetical order, proceeding to the next if we get a 403 of 5xx -response. +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. -So, an example setup would be:: +## Understanding the configuration - /etc/docker/certs.d/ - └── localhost - ├── client.cert - ├── client.key - └── localhost.crt +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. -A simple way to test this setup is to use an apache server to host a -registry. Just copy a registry tree into the apache root, -[here](http://people.gnome.org/~alexl/v1.tar.gz) is an example one -containing the busybox image. +> **Note:** +> In the absence of any root certificate authorities, Docker +> will use the system default (i.e., host's root CA set). -Then add this conf file as `/etc/httpd/conf.d/registry.conf`: +The presence of one or more `.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, 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 request. + + $ openssl genrsa -out client.key 1024 + $ 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]( +> http://people.gnome.org/~alexl/v1.tar.gz) - 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 + # which is not supported by the TLS implementation in go SSLVerifyClient optional_no_ca @@ -50,7 +86,8 @@ Then add this conf file as `/etc/httpd/conf.d/registry.conf`: Header set X-Docker-Endpoints "%{custom_host}e" -And this as `/var/www/cgi-bin/cert.cgi`: +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 @@ -73,11 +110,5 @@ And this as `/var/www/cgi-bin/cert.cgi`: cat $PATH_TRANSLATED -This will return 403 for all accessed to `/v1` unless any client cert is -presented. Obviously a real implementation would verify more details -about the certificate. - -Example client certs can be generated with:: - - openssl genrsa -out client.key 1024 - openssl req -new -x509 -text -key client.key -out client.cert +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.