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**
>
> 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