docker/docker_remote_api/docs/TLS-intro.rst

   1 Encrypt the docker remote API via TLS for Ubuntu and CentOS
   2
   3 [Introduction]
   4 The Docker daemon can listen to Docker Remote API requests via three types of
   5 Socket: unix, tcp and fd. By default, a unix domain socket (or IPC socket) is
   6 created at /var/run/docker.sock, requiring either root permission, or docker
   7 group membership.
   8
   9 Port 2375 is conventionally used for un-encrypted communition with Docker daemon
  10 remotely, where docker server can be accessed by any docker client via tcp socket
  11 in local area network. You can listen to port 2375 on all network interfaces with
  12 -H tcp://0.0.0.0:2375, where 0.0.0.0 means any available IP address on host, and
  13 tcp://0.0.0.0:2375 indicates that port 2375 is listened on any IP of daemon host.
  14 If we want to make docker server open on the Internet via TCP port, and only trusted
  15 clients have the right to access the docker server in a safe manner, port 2376 for
  16 encrypted communication with the daemon should be listened. It can be achieved to
  17 create certificate and distribute it to the trusted clients.
  18
  19 Through creating self-signed certificate, and using --tlsverify command when running
  20 Docker daemon, Docker daemon opens the TLS authentication. Thus only the clients
  21 with related private key files can have access to the Docker daemon's server. As
  22 long as the key files for encryption are secure between docker server and client,
  23 the Docker daemon can keep secure.
  24 In summary,
  25 Firstly we should create docker server certificate and related key files, which
  26 are distributed to the trusted clients.
  27 Then the clients with related key files can access docker server.
  28
  29 [Steps]
  30 1.0. Create a CA, server and client keys with OpenSSL.
  31     OpenSSL is used to generate certificate, and can be installed as follows.
  32     apt-get install openssl openssl-devel
  33
  34 1.1 First generate CA private and public keys.
  35     openssl genrsa -aes256 -out ca-key.pem 4096
  36     openssl req -new -x509 -days 365 -key ca-key.pem -sha256 -out ca.pem
  37
  38     You are about to be asked to enter information that will be incorporated
  39     into your certificate request, where the instance of $HOST should be replaced
  40     with the DNS name of your Docker daemon's host, here the DNS name of my Docker
  41     daemon is ly.
  42        Common Name (e.g. server FQDN or YOUR name) []:$HOST
  43
  44 1.2 Now we have a CA (ca-key.pem and ca.pem), you can create a server key and
  45 certificate signing request.
  46     openssl genrsa -out server-key.pem 4096
  47     openssl req -subj "/CN=$HOST" -sha256 -new -key server-key.pem -out server.csr
  48
  49 1.3 Sign the public key with our CA.
  50     TLS connections can be made via IP address as well as DNS name, they need to be
  51     specified when creating the certificate.
  52
  53     echo subjectAltName = IP:172.16.10.121,IP:127.0.0.1 > extfile.cnf
  54     openssl x509 -req -days 365 -sha256 -in server.csr -CA ca.pem -CAkey ca-key.pem \
  55     -CAcreateserial -out server-cert.pem -extfile extfile.cnf
  56
  57 1.4 For client authentication, create a client key and certificate signing request.
  58     openssl genrsa -out key.pem 4096
  59     openssl req -subj '/CN=client' -new -key key.pem -out client.csr
  60
  61 1.5 To make the key suitable for client authentication, create an extensions config file.
  62     echo extendedKeyUsage = clientAuth > extfile.cnf
  63
  64 1.6 Sign the public key and after generating cert.pem and server-cert.pem, two certificate
  65     signing requests can be removed.
  66     openssl x509 -req -days 365 -sha256 -in client.csr -CA ca.pem -CAkey ca-key.pem \
  67     -CAcreateserial -out cert.pem -extfile extfile.cnf
  68
  69 1.7 In order to protect your keys from accidental damage, you may change file modes to
  70     be only readable.
  71     chmod -v 0400 ca-key.pem key.pem server-key.pem
  72     chmod -v 0444 ca.pem server-cert.pem cert.pem
  73
  74 1.8 Build docker server
  75     dockerd --tlsverify --tlscacert=ca.pem --tlscert=server-cert.pem --tlskey=server-key.pem \
  76     -H=0.0.0.0:2376
  77     Then, it can be seen from the command 'netstat -ntlp' that port 2376 has been listened
  78     and the Docker daemon only accept connections from clients providing a certificate
  79     trusted by our CA.
  80
  81 1.9 Distribute the keys to the client
  82     scp /etc/docker/ca.pem wwl@172.16.10.121:/etc/docker
  83     scp /etc/docker/cert.pem wwl@172.16.10.121:/etc/docker
  84     scp /etc/docker/key.pem wwl@172.16.10.121:/etc/docker
  85     Where, wwl and 172.16.10.121 is the username and IP of the client respectively.
  86     And the password of the client is needed when you distribute the keys to the client.
  87
  88 1.10 To access Docker daemon from the client via keys.
  89     docker --tlsverify --tlscacert=ca.pem --tlscert=cert.pem --tlskey=key.pem \
  90     -H=$HOST:2376 version
  91
  92     Then we can operate docker in the Docker daemon from the client vis keys, for example:
  93     1) create container from the client
  94     docker --tlsverify --tlscacert=ca.pem --tlscert=cert.pem --tlskey=key.pem -H=ly:2376 run -d \
  95     -it --name w1 grafana/grafana
  96     2) list containers from the client
  97     docker --tlsverify --tlscacert=ca.pem --tlscert=cert.pem --tlskey=key.pem -H=ly:2376 pa -a
  98     3) stop/start containers from the client
  99     docker --tlsverify --tlscacert=ca.pem --tlscert=cert.pem --tlskey=key.pem -H=ly:2376 stop w1
 100     docker --tlsverify --tlscacert=ca.pem --tlscert=cert.pem --tlskey=key.pem -H=ly:2376 start w1
 101
 102
 103
 104
 105
 106
 107