Merge pull request #19511 from moxiegirl/19473-fix-certificate

Fixing missing certs article; consolidating security material

docs/articles/certificates.md

@@ -1,17 +0,0 @@
-<!--[metadata]>
-+++
-title = "Using certificates for repository client verification"
-description = "How to set up and use certificates with a registry to verify access"
-keywords = ["Usage, registry, repository, client, root, certificate, docker, apache, ssl, tls, documentation, examples, articles,  tutorials"]
-[menu.main]
-parent = "mn_docker_hub"
-weight = 7
-+++
-<![end-metadata]-->
-
-# 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. 

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.
 

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
 +++
 <![end-metadata]-->
 

docs/security/certificates.md

@@ -0,0 +1,85 @@
+<!--[metadata]>
++++
+aliases = ["/articles/certificates/"]
+title = "Using certificates for repository client verification"
+description = "How to set up and use certificates with a registry to verify access"
+keywords = ["Usage, registry, repository, client, root, certificate, docker, apache, ssl, tls, documentation, examples, articles,  tutorials"]
+[menu.main]
+parent = "smn_secure_docker"
++++
+<![end-metadata]-->
+
+# 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 `<filename>.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)

docs/security/https.md

@@ -1,11 +1,11 @@
 <!--[metadata]>
 +++
+aliases = ["/engine/articles/https/"]
 title = "Protect the Docker daemon socket"
 description = "How to setup and run Docker with HTTPS"
 keywords = ["docker, docs, article, example, https, daemon, tls, ca,  certificate"]
 [menu.main]
-parent = "smn_administrate"
-weight = 5
+parent = "smn_secure_docker"
 +++
 <![end-metadata]-->
 
@@ -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)

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).

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
 +++
 <![end-metadata]-->
 

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

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
 +++
 <![end-metadata]-->
@@ -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)
-