github.com/sijibomii/docker@v0.0.0-20231230191044-5cf6ca554647/docs/security/certificates.md (about)

     1  <!--[metadata]>
     2  +++
     3  aliases = ["/engine/articles/certificates/"]
     4  title = "Using certificates for repository client verification"
     5  description = "How to set up and use certificates with a registry to verify access"
     6  keywords = ["Usage, registry, repository, client, root, certificate, docker, apache, ssl, tls, documentation, examples, articles,  tutorials"]
     7  [menu.main]
     8  parent = "smn_secure_docker"
     9  +++
    10  <![end-metadata]-->
    11  
    12  # Using certificates for repository client verification
    13  
    14  In [Running Docker with HTTPS](https.md), you learned that, by default,
    15  Docker runs via a non-networked Unix socket and TLS must be enabled in order
    16  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.
    17  
    18  This article demonstrates how to ensure the traffic between the Docker registry (i.e., *a server*) and the Docker daemon (i.e., *a client*) traffic is encrypted and a properly authenticated using *certificate-based client-server authentication*.
    19  
    20  We will show you how to install a Certificate Authority (CA) root certificate
    21  for the registry and how to set the client TLS certificate for verification.
    22  
    23  ## Understanding the configuration
    24  
    25  A custom certificate is configured by creating a directory under
    26  `/etc/docker/certs.d` using the same name as the registry's hostname (e.g.,
    27  `localhost`). All `*.crt` files are added to this directory as CA roots.
    28  
    29  > **Note:**
    30  > In the absence of any root certificate authorities, Docker
    31  > will use the system default (i.e., host's root CA set).
    32  
    33  The presence of one or more `<filename>.key/cert` pairs indicates to Docker
    34  that there are custom certificates required for access to the desired
    35  repository.
    36  
    37  > **Note:**
    38  > If there are multiple certificates, each will be tried in alphabetical
    39  > order. If there is an authentication error (e.g., 403, 404, 5xx, etc.), Docker
    40  > will continue to try with the next certificate.
    41  
    42  The following illustrates a configuration with multiple certs:
    43  
    44  ```
    45      /etc/docker/certs.d/        <-- Certificate directory
    46      └── localhost               <-- Hostname
    47         ├── client.cert          <-- Client certificate
    48         ├── client.key           <-- Client key
    49         └── localhost.crt        <-- Certificate authority that signed
    50                                      the registry certificate
    51  ```
    52  
    53  The preceding example is operating-system specific and is for illustrative
    54  purposes only. You should consult your operating system documentation for
    55  creating an os-provided bundled certificate chain.
    56  
    57  
    58  ## Creating the client certificates
    59  
    60  You will use OpenSSL's `genrsa` and `req` commands to first generate an RSA
    61  key and then use the key to create the certificate.   
    62  
    63      $ openssl genrsa -out client.key 4096
    64      $ openssl req -new -x509 -text -key client.key -out client.cert
    65  
    66  > **Note:**
    67  > These TLS commands will only generate a working set of certificates on Linux.
    68  > The version of OpenSSL in Mac OS X is incompatible with the type of
    69  > certificate Docker requires.
    70  
    71  ## Troubleshooting tips
    72  
    73  The Docker daemon interprets ``.crt` files as CA certificates and `.cert` files
    74  as client certificates. If a CA certificate is accidentally given the extension
    75  `.cert` instead of the correct `.crt` extension, the Docker daemon logs the
    76  following error message:
    77  
    78  ```
    79  Missing key KEY_NAME for client certificate CERT_NAME. Note that CA certificates should use the extension .crt.
    80  ```
    81  
    82  ## Related Information
    83  
    84  * [Use trusted images](index.md)
    85  * [Protect the Docker daemon socket](https.md)