Merge pull request #9952 from flowlo/doc-https

doc: Improve article on HTTPS

docs/sources/articles/https.md

@@ -26,7 +26,7 @@ it will only connect to servers with a certificate signed by that CA.
 
 ## Create a CA, server and client keys with OpenSSL
 
-> **Note:** replace all instances of `$HOST` in the following example with the
+> **Note**: replace all instances of `$HOST` in the following example with the
 > DNS name of your Docker daemon's host.
 
 First generate CA private and public keys:
@@ -40,26 +40,26 @@ First generate CA private and public keys:
     Verifying - Enter pass phrase for ca-key.pem:
     $ openssl req -new -x509 -days 365 -key ca-key.pem -sha256 -out ca.pem
     Enter pass phrase for ca-key.pem:
-     You are about to be asked to enter information that will be incorporated
-     into your certificate request.
-     What you are about to enter is what is called a Distinguished Name or a DN.
-     There are quite a few fields but you can leave some blank
-     For some fields there will be a default value,
-     If you enter '.', the field will be left blank.
-     -----
-     Country Name (2 letter code) [AU]:
-     State or Province Name (full name) [Some-State]:Queensland
-     Locality Name (eg, city) []:Brisbane
-     Organization Name (eg, company) [Internet Widgits Pty Ltd]:Docker Inc
-     Organizational Unit Name (eg, section) []:Boot2Docker
-     Common Name (e.g. server FQDN or YOUR name) []:$HOST
-     Email Address []:Sven@home.org.au
+    You are about to be asked to enter information that will be incorporated
+    into your certificate request.
+    What you are about to enter is what is called a Distinguished Name or a DN.
+    There are quite a few fields but you can leave some blank
+    For some fields there will be a default value,
+    If you enter '.', the field will be left blank.
+    -----
+    Country Name (2 letter code) [AU]:
+    State or Province Name (full name) [Some-State]:Queensland
+    Locality Name (eg, city) []:Brisbane
+    Organization Name (eg, company) [Internet Widgits Pty Ltd]:Docker Inc
+    Organizational Unit Name (eg, section) []:Boot2Docker
+    Common Name (e.g. server FQDN or YOUR name) []:$HOST
+    Email Address []:Sven@home.org.au
 
 Now that we have a CA, you can create a server key and certificate
 signing request (CSR). Make sure that "Common Name" (i.e., server FQDN or YOUR
 name) matches the hostname you will use to connect to Docker:
 
-> **Note:** replace all instances of `$HOST` in the following example with the
+> **Note**: replace all instances of `$HOST` in the following example with the
 > DNS name of your Docker daemon's host.
 
     $ openssl genrsa -out server-key.pem 2048
@@ -69,7 +69,7 @@ name) matches the hostname you will use to connect to Docker:
     e is 65537 (0x10001)
     $ openssl req -subj "/CN=$HOST" -new -key server-key.pem -out server.csr
 
-Next, we're going to sign the key with our CA:
+Next, we're going to sign the public key with our CA:
 
     $ openssl x509 -req -days 365 -in server.csr -CA ca.pem -CAkey ca-key.pem \
       -CAcreateserial -out server-cert.pem
@@ -93,7 +93,7 @@ config file:
 
     $ echo extendedKeyUsage = clientAuth > extfile.cnf
 
-Now sign the key:
+Now sign the public key:
 
     $ openssl x509 -req -days 365 -in client.csr -CA ca.pem -CAkey ca-key.pem \
       -CAcreateserial -out cert.pem -extfile extfile.cnf
@@ -102,6 +102,24 @@ Now sign the key:
     Getting CA Private Key
     Enter pass phrase for ca-key.pem:
 
+After generating `cert.pem` and `server-cert.pem` you can safely remove the
+two certificate signing requests:
+
+    $ rm -v client.csr server.csr
+
+With a default `umask` of 022, your secret keys will be *world-readable* and
+writable for you and your group.
+
+In order to protect your keys from accidental damage, you will want to remove their
+write permissions. To make them only readable by you, change file modes as follows:
+
+    $ chmod -v 0400 ca-key.pem key.pem server-key.pem
+
+Certificates can be world-readable, but you might want to remove write access to
+prevent accidental damage:
+
+    $ chmod -v 0444 ca.pem server-cert.pem cert.pem
+
 Now you can make the Docker daemon only accept connections from clients
 providing a certificate trusted by our CA:
 
@@ -111,7 +129,7 @@ providing a certificate trusted by our CA:
 To be able to connect to Docker and validate its certificate, you now
 need to provide your client keys, certificates and trusted CA:
 
-> **Note:** replace all instances of `$HOST` in the following example with the
+> **Note**: replace all instances of `$HOST` in the following example with the
 > DNS name of your Docker daemon's host.
 
     $ docker --tlsverify --tlscacert=ca.pem --tlscert=cert.pem --tlskey=key.pem \
@@ -130,16 +148,13 @@ need to provide your client keys, certificates and trusted CA:
 ## Secure by default
 
 If you want to secure your Docker client connections by default, you can move
-the files to the `.docker` directory in your home directory - and set the
+the files to the `.docker` directory in your home directory -- and set the
 `DOCKER_HOST` and `DOCKER_TLS_VERIFY` variables as well (instead of passing
 `-H=tcp://:2376` and `--tlsverify` on every call).
 
-    $ mkdir -p ~/.docker
-    $ cp ca.pem ~/.docker/ca.pem
-    $ cp cert.pem ~/.docker/cert.pem
-    $ cp key.pem ~/.docker/key.pem
-    $ export DOCKER_HOST=tcp://:2376
-    $ export DOCKER_TLS_VERIFY=1
+    $ mkdir -pv ~/.docker
+    $ cp -v {ca,cert,key}.pem ~/.docker
+    $ export DOCKER_HOST=tcp://:2376 DOCKER_TLS_VERIFY=1
 
 Docker will now connect securely by default:
 
@@ -165,11 +180,11 @@ Docker in various other modes by mixing the flags.
    certificate and authenticate server based on given CA
 
 If found, the client will send its client certificate, so you just need
-to drop your keys into `~/.docker/<ca, cert or key>.pem`. Alternatively,
+to drop your keys into `~/.docker/{ca,cert,key}.pem`. Alternatively,
 if you want to store your keys in another location, you can specify that
 location using the environment variable `DOCKER_CERT_PATH`.
 
-    $ export DOCKER_CERT_PATH=${HOME}/.docker/zone1/
+    $ export DOCKER_CERT_PATH=~/.docker/zone1/
     $ docker --tlsverify ps
 
 ### Connecting to the Secure Docker port using `curl`