Merge pull request #9896 from flowlo/doc-https

doc: Improve article on HTTPS

docs/sources/articles/https.md

@@ -15,29 +15,27 @@ In the daemon mode, it will only allow connections from clients
 authenticated by a certificate signed by that CA. In the client mode,
 it will only connect to servers with a certificate signed by that CA.
 
-> **Warning**: 
+> **Warning**:
 > Using TLS and managing a CA is an advanced topic. Please familiarize yourself
 > with OpenSSL, x509 and TLS before using it in production.
 
 > **Warning**:
 > These TLS commands will only generate a working set of certificates on Linux.
-> Mac OS X comes with a version of OpenSSL that is incompatible with the 
+> Mac OS X comes with a version of OpenSSL that is incompatible with the
 > certificates that Docker requires.
 
 ## Create a CA, server and client keys with OpenSSL
 
-First, initialize the CA serial file and generate CA private and public
+First generate CA private and public keys:
-keys:
 
-    $ echo 01 > ca.srl
+    $ openssl genrsa -aes256 -out ca-key.pem 2048
-    $ openssl genrsa -des3 -out ca-key.pem 2048
     Generating RSA private key, 2048 bit long modulus
     ......+++
     ...............+++
     e is 65537 (0x10001)
     Enter pass phrase for ca-key.pem:
     Verifying - Enter pass phrase for ca-key.pem:
-    $ openssl req -new -x509 -days 365 -key ca-key.pem -out ca.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.
@@ -58,20 +56,17 @@ 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:
 
-    $ openssl genrsa -des3 -out server-key.pem 2048
+    $ openssl genrsa -out server-key.pem 2048
     Generating RSA private key, 2048 bit long modulus
     ......................................................+++
     ............................................+++
     e is 65537 (0x10001)
-    Enter pass phrase for server-key.pem:
-    Verifying - Enter pass phrase for server-key.pem:
     $ openssl req -subj '/CN=<Your Hostname Here>' -new -key server-key.pem -out server.csr
-    Enter pass phrase for server-key.pem:
 
 Next, we're going to sign the key with our CA:
 
     $ openssl x509 -req -days 365 -in server.csr -CA ca.pem -CAkey ca-key.pem \
-      -out server-cert.pem
+      -CAcreateserial -out server-cert.pem
     Signature ok
     subject=/CN=your.host.com
     Getting CA Private Key
@@ -80,15 +75,12 @@ Next, we're going to sign the key with our CA:
 For client authentication, create a client key and certificate signing
 request:
 
-    $ openssl genrsa -des3 -out key.pem 2048
+    $ openssl genrsa -out key.pem 2048
     Generating RSA private key, 2048 bit long modulus
     ...............................................+++
     ...............................................................+++
     e is 65537 (0x10001)
-    Enter pass phrase for key.pem:
-    Verifying - Enter pass phrase for key.pem:
     $ openssl req -subj '/CN=client' -new -key key.pem -out client.csr
-    Enter pass phrase for key.pem:
 
 To make the key suitable for client authentication, create an extensions
 config file:
@@ -98,21 +90,12 @@ config file:
 Now sign the key:
 
     $ openssl x509 -req -days 365 -in client.csr -CA ca.pem -CAkey ca-key.pem \
-      -out cert.pem -extfile extfile.cnf
+      -CAcreateserial -out cert.pem -extfile extfile.cnf
     Signature ok
     subject=/CN=client
     Getting CA Private Key
     Enter pass phrase for ca-key.pem:
 
-Finally, you need to remove the passphrase from the client and server key:
-
-    $ openssl rsa -in server-key.pem -out server-key.pem
-    Enter pass phrase for server-key.pem:
-    writing RSA key
-    $ openssl rsa -in key.pem -out key.pem
-    Enter pass phrase for key.pem:
-    writing RSA key
-
 Now you can make the Docker daemon only accept connections from clients
 providing a certificate trusted by our CA:
 
@@ -128,7 +111,7 @@ need to provide your client keys, certificates and trusted CA:
 > **Note**:
 > Docker over TLS should run on TCP port 2376.
 
-> **Warning**: 
+> **Warning**:
 > As shown in the example above, you don't have to run the `docker` client
 > with `sudo` or the `docker` group when you use certificate authentication.
 > That means anyone with the keys can give any instructions to your Docker
@@ -137,7 +120,7 @@ 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 
+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
 `DOCKER_HOST` and `DOCKER_TLS_VERIFY` variables as well (instead of passing
 `-H=tcp://:2376` and `--tlsverify` on every call).
@@ -184,4 +167,7 @@ location using the environment variable `DOCKER_CERT_PATH`.
 To use `curl` to make test API requests, you need to use three extra command line
 flags:
 
-    $ curl --insecure --cert ~/.docker/cert.pem --key ~/.docker/key.pem https://boot2docker:2376/images/json`
+    $ curl https://boot2docker:2376/images/json \
+      --cert ~/.docker/cert.pem \
+      --key ~/.docker/key.pem \
+      --cacert ~/.docker/ca.pem