diff --git a/docs/articles/certificates.md b/docs/articles/certificates.md deleted file mode 100644 index 84235f109c0503a3c969ebd0c15cbd0e19b0a4cc..0000000000000000000000000000000000000000 --- a/docs/articles/certificates.md +++ /dev/null @@ -1,17 +0,0 @@ - - -# Using certificates for repository client verification - -The original content was deprecated. For information about configuring -certificates, see [deploying a registry -server](http://docs.docker.com/registry/deploying). To reach an older version -of this content, refer to an older version of the documentation. diff --git a/docs/reference/commandline/daemon.md b/docs/reference/commandline/daemon.md index e59208033fade5820a116ade44d2fa6e8fdf0509..b84b097bbfaac71ea34beae1103fd4611aa55515 100644 --- a/docs/reference/commandline/daemon.md +++ b/docs/reference/commandline/daemon.md @@ -86,7 +86,7 @@ membership. If you need to access the Docker daemon remotely, you need to enable the `tcp` Socket. Beware that the default setup provides un-encrypted and un-authenticated direct access to the Docker daemon - and should be secured -either using the [built in HTTPS encrypted socket](../../articles/https/), or by +either using the [built in HTTPS encrypted socket](../../security/https/), or by putting a secure web proxy in front of it. You can listen on port `2375` on all network interfaces with `-H tcp://0.0.0.0:2375`, or on a particular network interface using its IP address: `-H tcp://192.168.59.103:2375`. It is @@ -220,15 +220,15 @@ options for `zfs` start with `zfs`. the empty case the larger the device is. The base device size can be increased at daemon restart which will allow - all future images and containers (based on those new images) to be of the + all future images and containers (based on those new images) to be of the new base device size. - Example use: + Example use: $ docker daemon --storage-opt dm.basesize=50G - This will increase the base device size to 50G. The Docker daemon will throw an - error if existing base device size is larger than 50G. A user can use + This will increase the base device size to 50G. The Docker daemon will throw an + error if existing base device size is larger than 50G. A user can use this option to expand the base device size however shrinking is not permitted. This value affects the system-wide "base" empty filesystem @@ -727,7 +727,7 @@ when querying the system for the subordinate group ID range. ### Detailed information on `subuid`/`subgid` ranges -Given potential advanced use of the subordinate ID ranges by power users, the +Given potential advanced use of the subordinate ID ranges by power users, the following paragraphs define how the Docker daemon currently uses the range entries found within the subordinate range files. diff --git a/docs/security/apparmor.md b/docs/security/apparmor.md index c33240dbfb5edea16f0eedf8ea6968dc6f0b426a..6b573478c5d17cbad3f6d9453b43b0cc51884115 100644 --- a/docs/security/apparmor.md +++ b/docs/security/apparmor.md @@ -5,6 +5,7 @@ description = "Enabling AppArmor in Docker" keywords = ["AppArmor, security, docker, documentation"] [menu.main] parent= "smn_secure_docker" +weight=5 +++ diff --git a/docs/security/certificates.md b/docs/security/certificates.md new file mode 100644 index 0000000000000000000000000000000000000000..ade4401443df29aa36f2744ba897912969760f89 --- /dev/null +++ b/docs/security/certificates.md @@ -0,0 +1,85 @@ + + +# Using certificates for repository client verification + +In [Running Docker with HTTPS](https.md), you learned that, by default, +Docker runs via a non-networked Unix socket and TLS must be enabled in order +to have the Docker client and the daemon communicate securely over HTTPS. TLS ensures authenticity of the registry endpoint and that traffic to/from registry is encrypted. + +This article demonstrates how to ensure the traffic between the Docker registry (i.e., *a server*) and the Docker daemon (i.e., *a client*) traffic is encrypted and a properly authenticated using *certificate-based client-server authentication*. + +We will show you how to install a Certificate Authority (CA) root certificate +for the registry and how to set the client TLS certificate for verification. + +## Understanding the configuration + +A custom certificate is configured by creating a directory under +`/etc/docker/certs.d` using the same name as the registry's hostname (e.g., +`localhost`). All `*.crt` files are added to this directory as CA roots. + +> **Note:** +> In the absence of any root certificate authorities, Docker +> will use the system default (i.e., host's root CA set). + +The presence of one or more `.key/cert` pairs indicates to Docker +that there are custom certificates required for access to the desired +repository. + +> **Note:** +> If there are multiple certificates, each will be tried in alphabetical +> order. If there is an authentication error (e.g., 403, 404, 5xx, etc.), Docker +> will continue to try with the next certificate. + +The following illustrates a configuration with multiple certs: + +``` + /etc/docker/certs.d/ <-- Certificate directory + └── localhost <-- Hostname + ├── client.cert <-- Client certificate + ├── client.key <-- Client key + └── localhost.crt <-- Certificate authority that signed + the registry certificate +``` + +The preceding example is operating-system specific and is for illustrative +purposes only. You should consult your operating system documentation for +creating an os-provided bundled certificate chain. + + +## Creating the client certificates + +You will use OpenSSL's `genrsa` and `req` commands to first generate an RSA +key and then use the key to create the certificate. + + $ openssl genrsa -out client.key 4096 + $ openssl req -new -x509 -text -key client.key -out client.cert + +> **Note:** +> These TLS commands will only generate a working set of certificates on Linux. +> The version of OpenSSL in Mac OS X is incompatible with the type of +> certificate Docker requires. + +## Troubleshooting tips + +The Docker daemon interprets ``.crt` files as CA certificates and `.cert` files +as client certificates. If a CA certificate is accidentally given the extension +`.cert` instead of the correct `.crt` extension, the Docker daemon logs the +following error message: + +``` +Missing key KEY_NAME for client certificate CERT_NAME. Note that CA certificates should use the extension .crt. +``` + +## Related Information + +* [Use trusted images](index.md) +* [Protect the Docker daemon socket](https.md) diff --git a/docs/articles/https.md b/docs/security/https.md similarity index 97% rename from docs/articles/https.md rename to docs/security/https.md index d7f016d8e050e3d61bc837f512a8c774db03a107..1b2619cb210066f112f3fbeb44c1d36c3cf79cf6 100644 --- a/docs/articles/https.md +++ b/docs/security/https.md @@ -1,11 +1,11 @@ @@ -209,3 +209,8 @@ flags: --cert ~/.docker/cert.pem \ --key ~/.docker/key.pem \ --cacert ~/.docker/ca.pem + +## Related information + +* [Using certificates for repository client verification](certificates.md) +* [Use trusted images](trust/index.md) diff --git a/docs/articles/https/Dockerfile b/docs/security/https/Dockerfile similarity index 100% rename from docs/articles/https/Dockerfile rename to docs/security/https/Dockerfile diff --git a/docs/articles/https/Makefile b/docs/security/https/Makefile similarity index 100% rename from docs/articles/https/Makefile rename to docs/security/https/Makefile diff --git a/docs/articles/https/README.md b/docs/security/https/README.md similarity index 100% rename from docs/articles/https/README.md rename to docs/security/https/README.md diff --git a/docs/articles/https/make_certs.sh b/docs/security/https/make_certs.sh similarity index 100% rename from docs/articles/https/make_certs.sh rename to docs/security/https/make_certs.sh diff --git a/docs/articles/https/parsedocs.sh b/docs/security/https/parsedocs.sh similarity index 100% rename from docs/articles/https/parsedocs.sh rename to docs/security/https/parsedocs.sh diff --git a/docs/security/index.md b/docs/security/index.md index 6948b097f7ff788b287aaaee97beab62de8db32d..e17085cd7dc6c9dafe3c63bb6bae352f96a3fb50 100644 --- a/docs/security/index.md +++ b/docs/security/index.md @@ -15,6 +15,10 @@ This section discusses the security features you can configure and use within yo * You can configure Docker's trust features so that your users can push and pull trusted images. To learn how to do this, see [Use trusted images](trust/index.md) in this section. +* You can protect the Docker daemon socket and ensure only trusted Docker client connections. For more information, [Protect the Docker daemon socket](https.md) + +* You can use certificate-based client-server authentication to verify a Docker daemon has the rights to access images on a registry. For more information, see [Using certificates for repository client verification](certificates.md). + * You can configure secure computing mode (Seccomp) policies to secure system calls in a container. For more information, see [Seccomp security profiles for Docker](seccomp.md). * An AppArmor profile for Docker is installed with the official *.deb* packages. For information about this profile and overriding it, see [AppArmor security profiles for Docker](apparmor.md). diff --git a/docs/security/seccomp.md b/docs/security/seccomp.md index b683be026be740af630320d3cf83da11b353b92f..c2f9968a544355da484904ff3d710a1047b36837 100644 --- a/docs/security/seccomp.md +++ b/docs/security/seccomp.md @@ -5,6 +5,7 @@ description = "Enabling seccomp in Docker" keywords = ["seccomp, security, docker, documentation"] [menu.main] parent= "smn_secure_docker" +weight=90 +++ diff --git a/docs/security/security.md b/docs/security/security.md index d6b11e466d63afc1bf8985356768eb64eb014466..ec24d879d88d4a04d3633f9872e21a8e7fde1457 100644 --- a/docs/security/security.md +++ b/docs/security/security.md @@ -116,7 +116,7 @@ However, if you do that, being aware of the above mentioned security implication, you should ensure that it will be reachable only from a trusted network or VPN; or protected with e.g., `stunnel` and client SSL certificates. You can also secure them with [HTTPS and -certificates](../articles/https/). +certificates](https.md). The daemon is also potentially vulnerable to other inputs, such as image loading from either disk with 'docker load', or from the network with diff --git a/docs/security/trust/index.md b/docs/security/trust/index.md index cace5e51a0f511f09504f7e5f08b25c2e85eff7e..9c2119da0ae254cd002876a4aac93820a83c7852 100644 --- a/docs/security/trust/index.md +++ b/docs/security/trust/index.md @@ -5,7 +5,7 @@ description = "Use trusted images" keywords = ["trust, security, docker, index"] [menu.main] identifier="smn_content_trust" -parent= "mn_docker_hub" +parent= "smn_secure_docker" weight=4 +++ @@ -14,8 +14,7 @@ weight=4 The following topics are available: -* [Content trust in Docker](content_trust.md) +* [Content trust in Docker](content_trust.md) * [Manage keys for content trust](trust_key_mng.md) * [Automation with content trust](trust_automation.md) * [Play in a content trust sandbox](trust_sandbox.md) -