docker/docker_remote_api/docs/TLS-intro.rst

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