From 02a793c6a133f46129d0fc83ce218d3a92f1e644 Mon Sep 17 00:00:00 2001 From: Lorenz Leutgeb Date: Wed, 7 Jan 2015 14:08:34 +0100 Subject: [PATCH] doc: Improve article on HTTPS * Adjust header to match _page_title * Add instructions on deletion of CSRs and setting permissions * Simplify some path expressions and commands * Consqeuently use ~ instead of ${HOME} * Precise formulation ('key' vs. 'public key') * Fix wrong indentation of output of `openssl req` * Use dash ('--') instead of minus ('-') Remark on permissions: It's not a problem to `chmod 0400` the private keys, because the Docker daemon runs as root (can read the file anyway) and the Docker client runs as user. Signed-off-by: Lorenz Leutgeb --- docs/sources/articles/https.md | 65 +++++++++++++++++++++------------- 1 file changed, 40 insertions(+), 25 deletions(-) diff --git a/docs/sources/articles/https.md b/docs/sources/articles/https.md index 41ba2cce5e..a79e28a5d4 100644 --- a/docs/sources/articles/https.md +++ b/docs/sources/articles/https.md @@ -40,20 +40,20 @@ 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 @@ -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. + +To remove write permissions for your keys in order to protect them from accidental +damage and make them only readable to you issue the following file mode changes: + + $ 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: @@ -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/.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`