diff --git a/engine/security/protect-access.md b/engine/security/protect-access.md index 376a11eb8c..00a1d5794c 100644 --- a/engine/security/protect-access.md +++ b/engine/security/protect-access.md @@ -16,10 +16,10 @@ optionally communicate using SSH or a TLS (HTTPS) socket. > **Note** > > The given `USERNAME` must have permissions to access the docker socket on the -> remote machine. Refer to [manage Docker as a non-root user](../../install/linux-postinstall/#manage-docker-as-a-non-root-user) +> remote machine. Refer to [manage Docker as a non-root user](../install/linux-postinstall.md#manage-docker-as-a-non-root-user) > to learn how to give a non-root user access to the docker socket. -The following example creates a [`docker context`](../../context/working-with-contexts/) +The following example creates a [`docker context`](../context/working-with-contexts.md) to connect with a remote `dockerd` daemon on `host1.example.com` using SSH, and as the `docker-user` user on the remote machine: @@ -98,30 +98,32 @@ it only connects to servers with a certificate signed by that CA. First, on the **Docker daemon's host machine**, generate CA private and public keys: - $ openssl genrsa -aes256 -out ca-key.pem 4096 - Generating RSA private key, 4096 bit long modulus - ............................................................................................................................................................................................++ - ........++ - e is 65537 (0x10001) - Enter pass phrase for ca-key.pem: - Verifying - Enter pass phrase for ca-key.pem: +```console +$ openssl genrsa -aes256 -out ca-key.pem 4096 +Generating RSA private key, 4096 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 -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) []:Sales - Common Name (e.g. server FQDN or YOUR name) []:$HOST - Email Address []:Sven@home.org.au +$ 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) []:Sales +Common Name (e.g. server FQDN or YOUR name) []:$HOST +Email Address []:Sven@home.org.au +``` Now that you have a CA, you can create a server key and certificate signing request (CSR). Make sure that "Common Name" matches the hostname you use @@ -130,13 +132,15 @@ to connect to Docker: > **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 4096 - Generating RSA private key, 4096 bit long modulus - .....................................................................++ - .................................................................................................++ - e is 65537 (0x10001) +```console +$ openssl genrsa -out server-key.pem 4096 +Generating RSA private key, 4096 bit long modulus +.....................................................................++ +.................................................................................................++ +e is 65537 (0x10001) - $ openssl req -subj "/CN=$HOST" -sha256 -new -key server-key.pem -out server.csr +$ openssl req -subj "/CN=$HOST" -sha256 -new -key server-key.pem -out server.csr +``` Next, we're going to sign the public key with our CA: @@ -144,7 +148,9 @@ Since TLS connections can be made through IP address as well as DNS name, the IP need to be specified when creating the certificate. For example, to allow connections using `10.10.10.20` and `127.0.0.1`: - $ echo subjectAltName = DNS:$HOST,IP:10.10.10.20,IP:127.0.0.1 >> extfile.cnf +```console +$ echo subjectAltName = DNS:$HOST,IP:10.10.10.20,IP:127.0.0.1 >> extfile.cnf +``` Set the Docker daemon key's extended usage attributes to be used only for server authentication: @@ -153,12 +159,14 @@ server authentication: Now, generate the signed certificate: - $ openssl x509 -req -days 365 -sha256 -in server.csr -CA ca.pem -CAkey ca-key.pem \ - -CAcreateserial -out server-cert.pem -extfile extfile.cnf - Signature ok - subject=/CN=your.host.com - Getting CA Private Key - Enter pass phrase for ca-key.pem: +```console +$ openssl x509 -req -days 365 -sha256 -in server.csr -CA ca.pem -CAkey ca-key.pem \ + -CAcreateserial -out server-cert.pem -extfile extfile.cnf +Signature ok +subject=/CN=your.host.com +Getting CA Private Key +Enter pass phrase for ca-key.pem: +``` [Authorization plugins](/engine/extend/plugins_authorization/) offer more fine-grained control to supplement authentication from mutual TLS. In addition @@ -172,13 +180,15 @@ request: > **Note**: For simplicity of the next couple of steps, you may perform this > step on the Docker daemon's host machine as well. - $ openssl genrsa -out key.pem 4096 - Generating RSA private key, 4096 bit long modulus - .........................................................++ - ................++ - e is 65537 (0x10001) +```console +$ openssl genrsa -out key.pem 4096 +Generating RSA private key, 4096 bit long modulus +.........................................................++ +................++ +e is 65537 (0x10001) - $ openssl req -subj '/CN=client' -new -key key.pem -out client.csr +$ openssl req -subj '/CN=client' -new -key key.pem -out client.csr +``` To make the key suitable for client authentication, create a new extensions config file: @@ -187,17 +197,21 @@ config file: Now, generate the signed certificate: - $ openssl x509 -req -days 365 -sha256 -in client.csr -CA ca.pem -CAkey ca-key.pem \ - -CAcreateserial -out cert.pem -extfile extfile-client.cnf - Signature ok - subject=/CN=client - Getting CA Private Key - Enter pass phrase for ca-key.pem: +```console +$ openssl x509 -req -days 365 -sha256 -in client.csr -CA ca.pem -CAkey ca-key.pem \ + -CAcreateserial -out cert.pem -extfile extfile-client.cnf +Signature ok +subject=/CN=client +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 and extensions config files: - $ rm -v client.csr server.csr extfile.cnf extfile-client.cnf +```console +$ rm -v client.csr server.csr extfile.cnf extfile-client.cnf +``` With a default `umask` of 022, your secret keys are *world-readable* and writable for you and your group. @@ -205,18 +219,28 @@ writable for you and your group. To protect your keys from accidental damage, 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 +```console +$ 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 +```console +$ 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 your CA: - $ dockerd --tlsverify --tlscacert=ca.pem --tlscert=server-cert.pem --tlskey=server-key.pem \ - -H=0.0.0.0:2376 +```console +$ dockerd \ + --tlsverify \ + --tlscacert=ca.pem \ + --tlscert=server-cert.pem \ + --tlskey=server-key.pem \ + -H=0.0.0.0:2376 +``` To connect to Docker and validate its certificate, provide your client keys, certificates and trusted CA: @@ -230,8 +254,13 @@ certificates and trusted CA: > **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 \ - -H=$HOST:2376 version +```console +$ docker --tlsverify \ + --tlscacert=ca.pem \ + --tlscert=cert.pem \ + --tlskey=key.pem \ + -H=$HOST:2376 version +``` > **Note**: > Docker over TLS should run on TCP port 2376. @@ -251,10 +280,12 @@ 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://$HOST:2376` and `--tlsverify` on every call). - $ mkdir -pv ~/.docker - $ cp -v {ca,cert,key}.pem ~/.docker +```console +$ mkdir -pv ~/.docker +$ cp -v {ca,cert,key}.pem ~/.docker - $ export DOCKER_HOST=tcp://$HOST:2376 DOCKER_TLS_VERIFY=1 +$ export DOCKER_HOST=tcp://$HOST:2376 DOCKER_TLS_VERIFY=1 +``` Docker now connects securely by default: @@ -284,18 +315,22 @@ 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=~/.docker/zone1/ - $ docker --tlsverify ps +```console +$ export DOCKER_CERT_PATH=~/.docker/zone1/ +$ docker --tlsverify ps +``` #### Connecting to the secure Docker port using `curl` To use `curl` to make test API requests, you need to use three extra command line flags: - $ curl https://$HOST:2376/images/json \ - --cert ~/.docker/cert.pem \ - --key ~/.docker/key.pem \ - --cacert ~/.docker/ca.pem +```console +$ curl https://$HOST:2376/images/json \ + --cert ~/.docker/cert.pem \ + --key ~/.docker/key.pem \ + --cacert ~/.docker/ca.pem +``` ## Related information