From f957f258d722fa563ead0a14978acca7c6745d3f Mon Sep 17 00:00:00 2001 From: Lorenz Leutgeb Date: Sun, 4 Jan 2015 20:57:20 +0100 Subject: [PATCH 1/4] doc: Do not encrypt private keys Do not encrypt private keys in the first place, if the encryption is stripped anyway. Signed-off-by: Lorenz Leutgeb --- docs/sources/articles/https.md | 27 ++++++--------------------- 1 file changed, 6 insertions(+), 21 deletions(-) diff --git a/docs/sources/articles/https.md b/docs/sources/articles/https.md index 2fe5162d66..ab5ed2095c 100644 --- a/docs/sources/articles/https.md +++ b/docs/sources/articles/https.md @@ -15,13 +15,13 @@ 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 @@ -58,15 +58,12 @@ 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=' -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: @@ -80,15 +77,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: @@ -104,15 +98,6 @@ Now sign the key: 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 +113,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 +122,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). From a3d5f874c108d3e7d58a7f86c0ef0eea6fcca85f Mon Sep 17 00:00:00 2001 From: Lorenz Leutgeb Date: Sun, 4 Jan 2015 21:15:30 +0100 Subject: [PATCH 2/4] doc: Spice up generated CA Use AES (the successor of DES) to encrypt private key. Further reading: * http://csrc.nist.gov/publications/nistpubs/800-131A/sp800-131A.pdf * https://ssllabs.com/downloads/SSL_TLS_Deployment_Best_Practices.pdf "3DES provides about 112 bits of security. This is below the recommended minimum of 128 bits, but it's still strong enough. A bigger practical problem is that 3DES is much slower than the alternatives. Thus, we don't recommend it for performance reasons, but it can be kept at the end of the cipher list for interoperability with very old clients." * http://csrc.nist.gov/publications/nistpubs/800-67-Rev1/SP-800-67-Rev1.pdf Use SHA256 for our CA. This avoids accidental use of SHA1 or MD5 which could be default values. Signed-off-by: Lorenz Leutgeb --- docs/sources/articles/https.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/sources/articles/https.md b/docs/sources/articles/https.md index ab5ed2095c..834206b0b4 100644 --- a/docs/sources/articles/https.md +++ b/docs/sources/articles/https.md @@ -30,14 +30,14 @@ First, initialize the CA serial file and generate CA private and public keys: $ echo 01 > ca.srl - $ openssl genrsa -des3 -out ca-key.pem 2048 + $ openssl genrsa -aes256 -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. From 131c62d7661ace86453de540cb1a58956b59e347 Mon Sep 17 00:00:00 2001 From: Lorenz Leutgeb Date: Sun, 4 Jan 2015 21:49:16 +0100 Subject: [PATCH 3/4] doc: Let OpenSSL handle serial file With -CAcreateserial the serial file will be automatically created and initialized if it is missing. Signed-off-by: Lorenz Leutgeb --- docs/sources/articles/https.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/sources/articles/https.md b/docs/sources/articles/https.md index 834206b0b4..925ba8f8f2 100644 --- a/docs/sources/articles/https.md +++ b/docs/sources/articles/https.md @@ -26,10 +26,8 @@ it will only connect to servers with a certificate signed by that CA. ## Create a CA, server and client keys with OpenSSL -First, initialize the CA serial file and generate CA private and public -keys: +First generate CA private and public keys: - $ echo 01 > ca.srl $ openssl genrsa -aes256 -out ca-key.pem 2048 Generating RSA private key, 2048 bit long modulus ......+++ @@ -68,7 +66,7 @@ name) matches the hostname you will use to connect to Docker: 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 @@ -92,7 +90,7 @@ 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 From 26187bd851141236a909c0bada5a2743fc237e0e Mon Sep 17 00:00:00 2001 From: Lorenz Leutgeb Date: Mon, 5 Jan 2015 01:24:33 +0100 Subject: [PATCH 4/4] doc: Fix curl invocation Using --insecure is (you guessed it) *insecure* as the server side certificate is not being validated. To offer the same degree of security as invocations of the docker client in "Secure by default" with cURL, the trusted CA certificate must be supplied. Signed-off-by: Lorenz Leutgeb --- docs/sources/articles/https.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/sources/articles/https.md b/docs/sources/articles/https.md index 925ba8f8f2..cf1ccaef6e 100644 --- a/docs/sources/articles/https.md +++ b/docs/sources/articles/https.md @@ -167,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