docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

engine/security/protect-access: markdown touch-ups 

- use "console" code hints for better copy/paste
- change links to point to markdown files

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
This commit is contained in:
Sebastiaan van Stijn 2021-05-11 16:08:22 +02:00
parent d491238592
commit 030ebcd114
No known key found for this signature in database
GPG Key ID: 76698F39D527CE8C
1 changed files with 101 additions and 66 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

167
engine/security/protect-access.md
View File

@ -16,10 +16,10 @@ optionally communicate using SSH or a TLS (HTTPS) socket.
> **Note** > **Note**
> >
> The given `USERNAME` must have permissions to access the docker socket on the > 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. > 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 to connect with a remote `dockerd` daemon on `host1.example.com` using SSH, and
as the `docker-user` user on the remote machine: 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: First, on the **Docker daemon's host machine**, generate CA private and public keys:
$ openssl genrsa -aes256 -out ca-key.pem 4096 ```console
Generating RSA private key, 4096 bit long modulus $ 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: e is 65537 (0x10001)
Verifying - Enter pass phrase for ca-key.pem: 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 $ openssl req -new -x509 -days 365 -key ca-key.pem -sha256 -out ca.pem
Enter pass phrase for ca-key.pem: Enter pass phrase for ca-key.pem:
You are about to be asked to enter information that will be incorporated You are about to be asked to enter information that will be incorporated
into your certificate request. into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN. 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 There are quite a few fields but you can leave some blank
For some fields there will be a default value, For some fields there will be a default value,
If you enter '.', the field will be left blank. If you enter '.', the field will be left blank.
----- -----
Country Name (2 letter code) [AU]: Country Name (2 letter code) [AU]:
State or Province Name (full name) [Some-State]:Queensland State or Province Name (full name) [Some-State]:Queensland
Locality Name (eg, city) []:Brisbane Locality Name (eg, city) []:Brisbane
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Docker Inc Organization Name (eg, company) [Internet Widgits Pty Ltd]:Docker Inc
Organizational Unit Name (eg, section) []:Sales Organizational Unit Name (eg, section) []:Sales
Common Name (e.g. server FQDN or YOUR name) []:$HOST Common Name (e.g. server FQDN or YOUR name) []:$HOST
Email Address []:Sven@home.org.au Email Address []:Sven@home.org.au
```
Now that you have a CA, you can create a server key and certificate 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 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 > **Note**: Replace all instances of `$HOST` in the following example with the
> DNS name of your Docker daemon's host. > DNS name of your Docker daemon's host.
$ openssl genrsa -out server-key.pem 4096 ```console
Generating RSA private key, 4096 bit long modulus $ openssl genrsa -out server-key.pem 4096
.....................................................................++ Generating RSA private key, 4096 bit long modulus
.................................................................................................++ .....................................................................++
e is 65537 (0x10001) .................................................................................................++
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: 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 need to be specified when creating the certificate. For example, to allow connections
using `10.10.10.20` and `127.0.0.1`: 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 Set the Docker daemon key's extended usage attributes to be used only for
server authentication: server authentication:
@ -153,12 +159,14 @@ server authentication:
Now, generate the signed certificate: Now, generate the signed certificate:
$ openssl x509 -req -days 365 -sha256 -in server.csr -CA ca.pem -CAkey ca-key.pem \ ```console
-CAcreateserial -out server-cert.pem -extfile extfile.cnf $ openssl x509 -req -days 365 -sha256 -in server.csr -CA ca.pem -CAkey ca-key.pem \
Signature ok -CAcreateserial -out server-cert.pem -extfile extfile.cnf
subject=/CN=your.host.com Signature ok
Getting CA Private Key subject=/CN=your.host.com
Enter pass phrase for ca-key.pem: Getting CA Private Key
Enter pass phrase for ca-key.pem:
```
[Authorization plugins](/engine/extend/plugins_authorization/) offer more [Authorization plugins](/engine/extend/plugins_authorization/) offer more
fine-grained control to supplement authentication from mutual TLS. In addition 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 > **Note**: For simplicity of the next couple of steps, you may perform this
> step on the Docker daemon's host machine as well. > step on the Docker daemon's host machine as well.
$ openssl genrsa -out key.pem 4096 ```console
Generating RSA private key, 4096 bit long modulus $ openssl genrsa -out key.pem 4096
.........................................................++ Generating RSA private key, 4096 bit long modulus
................++ .........................................................++
e is 65537 (0x10001) ................++
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 To make the key suitable for client authentication, create a new extensions
config file: config file:
@ -187,17 +197,21 @@ config file:
Now, generate the signed certificate: Now, generate the signed certificate:
$ openssl x509 -req -days 365 -sha256 -in client.csr -CA ca.pem -CAkey ca-key.pem \ ```console
-CAcreateserial -out cert.pem -extfile extfile-client.cnf $ openssl x509 -req -days 365 -sha256 -in client.csr -CA ca.pem -CAkey ca-key.pem \
Signature ok -CAcreateserial -out cert.pem -extfile extfile-client.cnf
subject=/CN=client Signature ok
Getting CA Private Key subject=/CN=client
Enter pass phrase for ca-key.pem: Getting CA Private Key
Enter pass phrase for ca-key.pem:
```
After generating `cert.pem` and `server-cert.pem` you can safely remove the After generating `cert.pem` and `server-cert.pem` you can safely remove the
two certificate signing requests and extensions config files: 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 With a default `umask` of 022, your secret keys are *world-readable* and
writable for you and your group. 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 To protect your keys from accidental damage, remove their
write permissions. To make them only readable by you, change file modes as follows: 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 Certificates can be world-readable, but you might want to remove write access to
prevent accidental damage: 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 Now you can make the Docker daemon only accept connections from clients
providing a certificate trusted by your CA: providing a certificate trusted by your CA:
$ dockerd --tlsverify --tlscacert=ca.pem --tlscert=server-cert.pem --tlskey=server-key.pem \ ```console
-H=0.0.0.0:2376 $ 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, To connect to Docker and validate its certificate, provide your client keys,
certificates and trusted CA: certificates and trusted CA:
@ -230,8 +254,13 @@ 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. > DNS name of your Docker daemon's host.
$ docker --tlsverify --tlscacert=ca.pem --tlscert=cert.pem --tlskey=key.pem \ ```console
-H=$HOST:2376 version $ docker --tlsverify \
--tlscacert=ca.pem \
--tlscert=cert.pem \
--tlskey=key.pem \
-H=$HOST:2376 version
```
> **Note**: > **Note**:
> Docker over TLS should run on TCP port 2376. > 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 `DOCKER_HOST` and `DOCKER_TLS_VERIFY` variables as well (instead of passing
`-H=tcp://$HOST:2376` and `--tlsverify` on every call). `-H=tcp://$HOST:2376` and `--tlsverify` on every call).
$ mkdir -pv ~/.docker ```console
$ cp -v {ca,cert,key}.pem ~/.docker $ 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: 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 if you want to store your keys in another location, you can specify that
location using the environment variable `DOCKER_CERT_PATH`. location using the environment variable `DOCKER_CERT_PATH`.
$ export DOCKER_CERT_PATH=~/.docker/zone1/ ```console
$ docker --tlsverify ps $ export DOCKER_CERT_PATH=~/.docker/zone1/
$ docker --tlsverify ps
```
#### Connecting to the secure Docker port using `curl` #### Connecting to the secure Docker port using `curl`
To use `curl` to make test API requests, you need to use three extra command line To use `curl` to make test API requests, you need to use three extra command line
flags: flags:
$ curl https://$HOST:2376/images/json \ ```console
--cert ~/.docker/cert.pem \ $ curl https://$HOST:2376/images/json \
--key ~/.docker/key.pem \ --cert ~/.docker/cert.pem \
--cacert ~/.docker/ca.pem --key ~/.docker/key.pem \
--cacert ~/.docker/ca.pem
```
## Related information ## Related information