In the ‘learn how to use the Docker API’ tutorial, we introduced the Docker remote API and demonstrated how to use the API to manage images and containers. In that tutorial, we noted that the way Docker API was used was insecure and we introduced the use of a local certificate authority (CA). In this tutorial, we will discuss how we can use SSL and TSL to secure the Docker API in a production environment.
Before we can start securing the Docker API, there are several concepts that you need to understand. These are openSSL, TLS and x509. OpenSSL is an implementation of SSL which is a protocol that is used in secure transmission of information over the internet. SSL makes transmission of information secure by encrypting information to prevent unintended people from seeing it. SSL is mostly used over the HTTP protocol such as in web browsing but other protocols such as file transfer protocol (FTP) and simple mail transfer protocol (SMTP) can still use SSL. Netscape originally developed SSL which evolved to TLS. X.509 has been specified by the International Telecommunications Union as a standard for digital certificates. The specification sets out the characteristics and information needed in the identification of people and information systems. X.509 has found use in securely managing and distributing digital certificates over secure networks.
TSL/SSL has several benefits
- TLS/SSL operates on major web browsers, operating systems and web servers. It can be used on Windows and Unix systems.
- TLS/SSL can be relied on to transmit data securely. Servers and clients can be authenticated for identity proof. Besides offering protection against data revelation, it offers protection from masquerade attacks, man in the middle and roll back attacks.
- TLS/SSL is very flexible. It offers different ways of authentication, different hashing and encryption algorithms.
- Deployment and use of TLS/SSL is easy.
TLS/SSL has its benefits but it also has its downsides that you need to be aware of. Processor work load increases because of cryptographic processing but it is not possible to quantify resource use. The administrative effort also increases because of system configuration and certificate management.
A CA gives digital certificates for authenticating people, devices and websites over the internet. The CA conducts due diligence to verify identity before issuing a certificate.
To secure a Docker API on ubuntu we need openSSL installed. Use this openssl version command to check if openSSL is installed and return its version. We can also list all cipher algorithms available using this openssl ciphers -v command. The output of these commands is shown below
To begin the process of securing docker we need to generate private and public keys of CA. The commands below will show you how to do that.
sudo openssl genrsa -aes256 -out ca-key.pem 4096 sudo openssl req -new -x509 -days 365 -key ca-key.pem -sha256 -out ca.pem
After creating a CA we need to create a server key and a certificate signing request (CSR). To create the server key, we need to provide a FQDN of the host we will use to connect to Docker. Here we will use example.com for demonstration so you need to replace this with the correct FQDN.
The commands below create a server key and a CSR
sudo openssl genrsa -out server-key.pem 4096 openssl req -subj "/CN=example.com" -sha256 -new -key server-key.pem -out server.csr
The next step is signing the public key with our certificate authority. We need to specify the IP addresses and the DNS names that are allowed connection. For instance to include 127.0.0.1 we need to add it as shown below.
echo subjectAltName = IP:127.0.0.1 > extfile.cnf sudo openssl x509 -req -days 365 -sha256 -in server.csr -CA ca.pem -CAkey ca-key.pem \ -CAcreateserial -out server-cert.pem -extfile extfile.cnf
To enable client authentication we need to create a client key and a CSR. The commands below accomplish that
sudo openssl genrsa -out key.pem 4096 openssl req -subj '/CN=client' -new -key key.pem -out client.csr
We can customize the key, so that it can be used to authenticate the clients, using the command below.
echo extendedKeyUsage = clientAuth > extfile.cnf
We need to sign the public key as shown below:
sudo openssl x509 -req -days 365 -sha256 -in client.csr -CA ca.pem -CAkey ca-key.pem \ -CAcreateserial -out cert.pem -extfile extfile.cnf
Once the certificates have been created, we can remove CSR using the command shown below:
The keys and certificates are sensitive information so we can protect them by removing the write permissions. The commands below accomplish that:
sudo chmod -v 0400 ca-key.pem key.pem server-key.pem sudo chmod -v 0444 ca.pem server-cert.pem cert.pem
To instruct Docker to accept only connections from clients with a trusted certificate, use the command below.
sudo dockerd --tlsverify --tlscacert=ca.pem --tlscert=server-cert.pem --tlskey=server-key.pem -H=0.0.0.0:2376
To make a connection to Docker we need to provide client keys, certificates and a trusted CA so that the certificate is validated. The command below is used to accomplish that. You need to replace example.com with the FQDN of the domain you are connecting from:
docker --tlsverify --tlscacert=ca.pem --tlscert=cert.pem --tlskey=key.pem \ -H=example.com:2376 version
Instead of passing flags to every call we can move the keys, certificates and certificate authority to the home directory. We can then export variables. The commands below show how to complete that.
sudo mkdir -pv ~/.docker
sudo cp -v {ca,cert,key}.pem ~/.docker
export DOCKER_HOST=tcp://example.com:2376 DOCKER_TLS_VERIFY=1
In this article, we introduced TSL/SSL as way of securing information sent over the internet. We discussed concepts of SSL, TSL, X.509 that are related. We identified strengths and shortcomings of SSL/TSL. We discussed the process of creating a CA, creating certificates and signing them. We discussed how to use keys and certificates to secure a connection to Docker.
