github.com/feiyang21687/docker@v1.5.0/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.