Security configuration

Estimated reading time: 6 minutes

This document describes the security settings you need to configure.

  • SSL Certificate: Used to enter the hash (string) from the SSL Certificate. This cert must be accompanied by its private key, entered below.
  • SSL Private Key: The hash from the private key associated with the provided SSL Certificate (as a standard x509 key pair).

The Trusted Registry requires encrypted communications through HTTPS/SSL between (a) the Trusted Registry and your Docker Engine(s), and (b) between your web browser and the Trusted Registry admin server. There are a few options for setting this up:

  1. You can use the self-signed certificate Docker Trusted Registry generates by default.
  2. You can generate your own certificates using a public service or your enterprise’s infrastructure. See the Generating SSL certificates section for the options available.

If you are generating your own certificates, you can install them by following the instructions for Adding your own registry certificates to Docker Trusted Registry.

However, if you choose to use the Trusted Registry-generated certificates, or the certificates you generate yourself are not trusted by your client Docker hosts, you will need to do one of the following:

  • Install a registry certificate on all of your client Docker daemons, or

  • Set your client Docker daemons to run with an unconfirmed connection to the registry.

Generate SSL certificates

There are three basic approaches to generating certificates:

  1. Most enterprises will have private key infrastructure (PKI) in place to generate keys. Consult with your security team or whomever manages your private key infrastructure. If you have this resource available, Docker recommends you use it.

  2. If your enterprise can’t provide keys, you can use a public Certificate Authority (CA) like “InstantSSL.com” or “RapidSSL.com” to generate a certificate. If your certificates are generated using a globally trusted Certificate Authority, you don’t need to install them on all of your client Docker daemons.

  3. Use the self-signed registry certificate generated by Docker Trusted Registry, and install it onto the client Docker daemon hosts as seen in the following section.

Add your own registry certificates

Whichever method you use to generate certificates, once you have them you can set up your Trusted Registry server to use them.

  1. Navigate to Settings > Security, and put the SSL Certificate text (including all intermediate Certificates, starting with the host) into the “SSL Certificate” edit box, and the previously generated Private key into the “SSL Private Key” edit box.

  2. Click Save, and then wait for the Trusted Registry Admin site to restart and reload. It should now be using the new certificate. Once the Security page has reloaded, it displays # hashes instead of the certificate text you pasted.

If your certificate is signed by a chain of Certificate Authorities that are already trusted by your Docker daemon servers, you can skip the following “Install registry certificates” step.

Install registry certificates on client Docker daemons

If your certificates do not have a trusted Certificate Authority, you will need to install them on each client Docker daemon host.

The procedure for installing the Trusted Registry certificates on each Linux distribution has slightly different steps.

You can test this certificate using curl:

$ curl https://dtr.yourdomain.com/v2/
curl: (60) SSL certificate problem: self signed certificate

For details see: http://curl.haxx.se/docs/sslcerts.html

Curl performs SSL certificate verification by default, using a “bundle” of Certificate Authority (CA) public keys (CA certs). If the default bundle file isn’t adequate, you can specify an alternate file using the --cacert option. If this HTTPS server uses a certificate signed by a CA represented in the bundle, the certificate verification probably failed due to a problem with the certificate. For example, it might be expired, or the name might not match the domain name in the URL.

If you’d like to turn off curl’s verification of the certificate, use the -k (or --insecure) option.

$ curl --cacert /usr/local/etc/dtr/ssl/server.pem https://dtr.yourdomain.com/v2/
{"errors":[{"code":"UNAUTHORIZED","message":"access to the requested resource is not authorized","detail":null}]}

Continue by following the steps corresponding to your chosen OS. Run the following commands on the Trusted Registry host.

Ubuntu/Debian

$ export DOMAIN_NAME=dtr.yourdomain.com
$ openssl s_client -connect $DOMAIN_NAME:443 -showcerts </dev/null 2>/dev/null | openssl x509 -outform PEM | sudo tee /usr/local/share/ca-certificates/$DOMAIN_NAME.crt
$ sudo update-ca-certificates
Updating certificates in /etc/ssl/certs... 1 added, 0 removed; done.
Running hooks in /etc/ca-certificates/update.d....done.
$ sudo service docker restart
docker stop/waiting
docker start/running, process 29291

RHEL/Centos

$ export DOMAIN_NAME=dtr.yourdomain.com
$ openssl s_client -connect $DOMAIN_NAME:443 -showcerts </dev/null 2>/dev/null | openssl x509 -outform PEM | sudo tee /etc/pki/ca-trust/source/anchors/$DOMAIN_NAME.crt
$ sudo update-ca-trust
$ sudo /bin/systemctl restart docker.service

Docker Machine and Boot2Docker

You need to make some persistent changes using bootsync.sh in your Boot2Docker-based virtual machine (as documented in local customization). To do this:

  1. docker-machine ssh dev to enter the VM
  2. vi /var/lib/boot2docker/bootsync.sh creates it if it doesn’t exist, or edit it if it does.

  3. Install the CA cert (or the auto-generated cert) by adding the following code to your /var/lib/boot2docker/bootsync.sh:

    #!/bin/sh

cat /var/lib/boot2docker/server.pem >> /etc/ssl/certs/ca-certificates.crt

  4. Next get the certificate from the new Docker Trusted Registry server using:

    $ openssl s_client -connect dtr.yourdomain.com:443 -showcerts </dev/null 2>/dev/null | openssl x509 -outform PEM | sudo tee -a /var/lib/boot2docker/server.pem

    If your certificate chain is complicated, you can use the changes in Pull request 807

  5. Either reboot your virtual machine, or run the following commands to install the server certificate. Restart the Docker daemon.

    $ sudo chmod 755 /var/lib/boot2docker/bootsync.sh
$ sudo /var/lib/boot2docker/bootsync.sh
$ sudo /etc/init.d/docker restart`.

If you can’t install the certificates

If for some reason you can’t install the certificate chain on a client Docker host, or your certificates do not have a global CA, you can configure your Docker daemon to run in “insecure” mode. This is done by adding an extra flag, --insecure-registry host-ip|domain-name, to your client Docker daemon startup flags. Restart the Docker daemon for the change to take effect.

This flag means that the communications between your Docker client and the Trusted Registry server are still encrypted, but the client Docker daemon is not confirming that the Registry connection is not being hijacked or diverted.

If you enter a “Domain Name” into the Security settings, it needs to be DNS resolvable on any client daemons that are running in insecure-registry mode.

To set the flag, edit the daemon.json file, which is located in /etc/docker/ on Linux or C:\ProgramData\docker\config\ on Windows Server. If the file does not yet exist, create it. Assuming the file was empty, it should have the following contents:

{
  "insecure-registries": ["dtr.yourdomain.com"]
}

Restart Docker for the change to take effect.

Docker Machine and Boot2Docker

In your Boot2Docker-based virtual machine, customize the Docker daemon configuration with the /var/lib/boot2docker/profile file.

Open or create the /var/lib/boot2docker/profile file, and add an EXTRA_ARGS setting as follows:

EXTRA_ARGS="--insecure-registry dtr.yourdomain.com"

Restart Docker for the change to take effect.

See also

Rate this page:

 
1
 
1