deleted file mode 100644

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

deleted file mode 100644

@@ -1,211 +0,0 @@

-<!--[metadata]>

-+++

-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

-+++

-<![end-metadata]-->

-

-# Protect the Docker daemon socket

-

-By default, Docker runs via a non-networked Unix socket. It can also

-optionally communicate using a HTTP socket.

-

-If you need Docker to be reachable via the network in a safe manner, you can

-enable TLS by specifying the `tlsverify` flag and pointing Docker's

-`tlscacert` flag to a trusted CA certificate.

-

-In the daemon mode, it will only allow connections from clients

-authenticated by a certificate signed by that CA. In the client mode,

-it will only connect to servers with a certificate signed by that CA.

-

-> **Warning**:

-> Using TLS and managing a CA is an advanced topic. Please familiarize yourself

-> with OpenSSL, x509 and TLS before using it in production.

-

-> **Warning**:

-> These TLS commands will only generate a working set of certificates on Linux.

-> Mac OS X comes with a version of OpenSSL that is incompatible with the

-> certificates that Docker requires.

-

-## Create a CA, server and client keys with OpenSSL

-

-> **Note**: replace all instances of `$HOST` in the following example with the

-> DNS name of your Docker daemon's host.

-

-First 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:

-    $ 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 we have a CA, you can create a server key and certificate

-signing request (CSR). Make sure that "Common Name" (i.e., server FQDN or YOUR

-name) matches the hostname you will use 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)

-    $ 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:

-

-Since TLS connections can be made via IP address as well as DNS name, they 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 = IP:10.10.10.20,IP:127.0.0.1 > extfile.cnf

-

-    $ 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:

-

-For client authentication, create a client key and certificate signing

-request:

-

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

-

-To make the key suitable for client authentication, create an extensions

-config file:

-

-    $ echo extendedKeyUsage = clientAuth > extfile.cnf

-

-Now sign the public key:

-

-    $ openssl x509 -req -days 365 -sha256 -in client.csr -CA ca.pem -CAkey ca-key.pem \

-      -CAcreateserial -out cert.pem -extfile extfile.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:

-

-    $ rm -v client.csr server.csr

-

-With a default `umask` of 022, your secret keys will be *world-readable* and

-writable for you and your group.

-

-In order to protect your keys from accidental damage, you will want to 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

-

-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

-

-Now you can make the Docker daemon only accept connections from clients

-providing a certificate trusted by our CA:

-

-    $ docker daemon --tlsverify --tlscacert=ca.pem --tlscert=server-cert.pem --tlskey=server-key.pem \

-      -H=0.0.0.0:2376

-

-To be able to connect to Docker and validate its certificate, you now

-need to provide your client keys, 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

-

-> **Note**:

-> Docker over TLS should run on TCP port 2376.

-

-> **Warning**:

-> As shown in the example above, you don't have to run the `docker` client

-> with `sudo` or the `docker` group when you use certificate authentication.

-> That means anyone with the keys can give any instructions to your Docker

-> daemon, giving them root access to the machine hosting the daemon. Guard

-> these keys as you would a root password!

-

-## Secure by default

-

-If you want to secure your Docker client connections by default, you can move

-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

-    $ export DOCKER_HOST=tcp://$HOST:2376 DOCKER_TLS_VERIFY=1

-

-Docker will now connect securely by default:

-

-    $ docker ps

-

-## Other modes

-

-If you don't want to have complete two-way authentication, you can run

-Docker in various other modes by mixing the flags.

-

-### Daemon modes

-

- - `tlsverify`, `tlscacert`, `tlscert`, `tlskey` set: Authenticate clients

- - `tls`, `tlscert`, `tlskey`: Do not authenticate clients

-

-### Client modes

-

- - `tls`: Authenticate server based on public/default CA pool

- - `tlsverify`, `tlscacert`: Authenticate server based on given CA

- - `tls`, `tlscert`, `tlskey`: Authenticate with client certificate, do not

-   authenticate server based on given CA

- - `tlsverify`, `tlscacert`, `tlscert`, `tlskey`: Authenticate with client

-   certificate and authenticate server based on given CA

-

-If found, the client will send its client certificate, so you just need

-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

-

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

deleted file mode 100644

@@ -1,10 +0,0 @@

-FROM debian

-

-RUN apt-get update && apt-get install -yq openssl

-

-ADD make_certs.sh /

-

-

-WORKDIR /data

-VOLUME ["/data"]

-CMD /make_certs.sh

deleted file mode 100644

@@ -1,24 +0,0 @@

-

-HOST:=boot2docker

-

-makescript:

-	./parsedocs.sh > make_certs.sh

-

-build: clean makescript

-	docker build -t makecerts .

-

-cert: build

-	docker run --rm -it -v $(CURDIR):/data -e HOST=$(HOST) -e YOUR_PUBLIC_IP=$(shell ip a | grep "inet " | sed "s/.*inet \([0-9.]*\)\/.*/\1/" | xargs echo | sed "s/ /,IP:/g") makecerts

-

-certs: cert

-

-run:

-	sudo docker daemon -D --tlsverify --tlscacert=ca.pem --tlscert=server-cert.pem --tlskey=server-key.pem -H=0.0.0.0:6666 --pidfile=$(pwd)/docker.pid --graph=$(pwd)/graph

-

-client:

-	sudo docker --tls --tlscacert=ca.pem --tlscert=cert.pem --tlskey=key.pem   -H=$(HOST):6666 version

-	sudo docker --tlsverify --tlscacert=ca.pem --tlscert=cert.pem --tlskey=key.pem   -H=$(HOST):6666 info

-	sudo curl https://$(HOST):6666/images/json --cert ./cert.pem --key ./key.pem --cacert ./ca.pem

-

-clean:

-	rm -f ca-key.pem ca.pem ca.srl cert.pem client.csr extfile.cnf key.pem server-cert.pem server-key.pem server.csr extfile.cnf

deleted file mode 100644

@@ -1,32 +0,0 @@

-<!--[metadata]>

-+++

-draft = true

-+++

-<![end-metadata]-->

-

-

-

-This is an initial attempt to make it easier to test the examples in the https.md

-doc

-

-at this point, it has to be a manual thing, and I've been running it in boot2docker

-

-so my process is

-

-$ boot2docker ssh

-$$ git clone https://github.com/docker/docker

-$$ cd docker/docs/articles/https

-$$ make cert

-lots of things to see and manually answer, as openssl wants to be interactive

-**NOTE:** make sure you enter the hostname (`boot2docker` in my case) when prompted for `Computer Name`)

-$$ sudo make run

-

-start another terminal

-

-$ boot2docker ssh

-$$ cd docker/docs/articles/https

-$$ make client

-

-the last will connect first with `--tls` and then with `--tlsverify`

-

-both should succeed

deleted file mode 100755

@@ -1,23 +0,0 @@

-#!/bin/sh

-openssl genrsa -aes256 -out ca-key.pem 2048

-openssl req -new -x509 -days 365 -key ca-key.pem -sha256 -out ca.pem

-openssl genrsa -out server-key.pem 2048

-openssl req -subj "/CN=$HOST" -new -key server-key.pem -out server.csr

-echo subjectAltName = IP:$YOUR_PUBLIC_IP > extfile.cnf

-openssl x509 -req -days 365 -in server.csr -CA ca.pem -CAkey ca-key.pem       -CAcreateserial -out server-cert.pem -extfile extfile.cnf

-openssl genrsa -out key.pem 2048

-openssl req -subj '/CN=client' -new -key key.pem -out client.csr

-echo extendedKeyUsage = clientAuth > extfile.cnf

-openssl x509 -req -days 365 -in client.csr -CA ca.pem -CAkey ca-key.pem       -CAcreateserial -out cert.pem -extfile extfile.cnf

-rm -v client.csr server.csr

-chmod -v 0400 ca-key.pem key.pem server-key.pem

-chmod -v 0444 ca.pem server-cert.pem cert.pem

-# docker -d --tlsverify --tlscacert=ca.pem --tlscert=server-cert.pem --tlskey=server-key.pem       -H=0.0.0.0:7778

-# docker --tlsverify --tlscacert=ca.pem --tlscert=cert.pem --tlskey=key.pem       -H=$HOST:7778 version

-mkdir -pv ~/.docker

-cp -v {ca,cert,key}.pem ~/.docker

-export DOCKER_HOST=tcp://$HOST:7778 DOCKER_TLS_VERIFY=1

-# docker ps

-export DOCKER_CERT_PATH=~/.docker/zone1/

-# docker --tlsverify ps

-# curl https://$HOST:7778/images/json       --cert ~/.docker/cert.pem       --key ~/.docker/key.pem       --cacert ~/.docker/ca.pem

deleted file mode 100755

@@ -1,10 +0,0 @@

-#!/bin/sh

-

-echo "#!/bin/sh"

-cat ../https.md | awk '{if (sub(/\\$/,"")) printf "%s", $0; else print $0}' \

-        | grep '   $ ' \

-        | sed 's/    $ //g' \

-        | sed 's/2375/7777/g' \

-        | sed 's/2376/7778/g' \

-        | sed 's/^docker/# docker/g' \

-        | sed 's/^curl/# curl/g'

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

@@ -5,6 +5,7 @@ description = "Enabling AppArmor in Docker"

 keywords = ["AppArmor, security, docker, documentation"]

 [menu.main]

 parent= "smn_secure_docker"

+weight=5

 +++

 <![end-metadata]-->

new file mode 100644

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

new file mode 100644

@@ -0,0 +1,216 @@

+<!--[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_secure_docker"

+<![end-metadata]-->

+

+# Protect the Docker daemon socket

+

+By default, Docker runs via a non-networked Unix socket. It can also

+optionally communicate using a HTTP socket.

+

+If you need Docker to be reachable via the network in a safe manner, you can

+enable TLS by specifying the `tlsverify` flag and pointing Docker's

+`tlscacert` flag to a trusted CA certificate.

+

+In the daemon mode, it will only allow connections from clients

+authenticated by a certificate signed by that CA. In the client mode,

+it will only connect to servers with a certificate signed by that CA.

+

+> **Warning**:

+> Using TLS and managing a CA is an advanced topic. Please familiarize yourself

+> with OpenSSL, x509 and TLS before using it in production.

+

+> **Warning**:

+> These TLS commands will only generate a working set of certificates on Linux.

+> Mac OS X comes with a version of OpenSSL that is incompatible with the

+> certificates that Docker requires.

+

+## Create a CA, server and client keys with OpenSSL

+

+> **Note**: replace all instances of `$HOST` in the following example with the

+> DNS name of your Docker daemon's host.

+

+First 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:

+    $ 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 we have a CA, you can create a server key and certificate

+signing request (CSR). Make sure that "Common Name" (i.e., server FQDN or YOUR

+name) matches the hostname you will use 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)

+    $ 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:

+

+Since TLS connections can be made via IP address as well as DNS name, they 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 = IP:10.10.10.20,IP:127.0.0.1 > extfile.cnf

+

+    $ 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:

+

+For client authentication, create a client key and certificate signing

+request:

+

+    $ 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

+

+To make the key suitable for client authentication, create an extensions

+config file:

+

+    $ echo extendedKeyUsage = clientAuth > extfile.cnf

+

+Now sign the public key:

+

+    $ openssl x509 -req -days 365 -sha256 -in client.csr -CA ca.pem -CAkey ca-key.pem \

+      -CAcreateserial -out cert.pem -extfile extfile.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:

+

+    $ rm -v client.csr server.csr

+

+With a default `umask` of 022, your secret keys will be *world-readable* and

+writable for you and your group.

+

+In order to protect your keys from accidental damage, you will want to 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

+

+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

+

+Now you can make the Docker daemon only accept connections from clients

+providing a certificate trusted by our CA:

+

+    $ docker daemon --tlsverify --tlscacert=ca.pem --tlscert=server-cert.pem --tlskey=server-key.pem \

+      -H=0.0.0.0:2376

+

+To be able to connect to Docker and validate its certificate, you now

+need to provide your client keys, 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

+

+> **Note**:

+> Docker over TLS should run on TCP port 2376.

+

+> **Warning**:

+> As shown in the example above, you don't have to run the `docker` client

+> with `sudo` or the `docker` group when you use certificate authentication.

+> That means anyone with the keys can give any instructions to your Docker

+> daemon, giving them root access to the machine hosting the daemon. Guard

+> these keys as you would a root password!

+

+## Secure by default

+

+If you want to secure your Docker client connections by default, you can move

+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

+    $ export DOCKER_HOST=tcp://$HOST:2376 DOCKER_TLS_VERIFY=1

+

+Docker will now connect securely by default:

+

+    $ docker ps

+

+## Other modes

+

+If you don't want to have complete two-way authentication, you can run

+Docker in various other modes by mixing the flags.

+

+### Daemon modes

+

+ - `tlsverify`, `tlscacert`, `tlscert`, `tlskey` set: Authenticate clients

+ - `tls`, `tlscert`, `tlskey`: Do not authenticate clients

+

+### Client modes

+

+ - `tls`: Authenticate server based on public/default CA pool

+ - `tlsverify`, `tlscacert`: Authenticate server based on given CA

+ - `tls`, `tlscert`, `tlskey`: Authenticate with client certificate, do not

+   authenticate server based on given CA

+ - `tlsverify`, `tlscacert`, `tlscert`, `tlskey`: Authenticate with client

+   certificate and authenticate server based on given CA

+

+If found, the client will send its client certificate, so you just need

+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

+

+### 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

+

+## Related information

+

+* [Using certificates for repository client verification](certificates.md)

+* [Use trusted images](trust/index.md)

new file mode 100644

@@ -0,0 +1,10 @@

+FROM debian

+

+RUN apt-get update && apt-get install -yq openssl

+

+ADD make_certs.sh /

+

+

+WORKDIR /data

+VOLUME ["/data"]

+CMD /make_certs.sh

new file mode 100644

@@ -0,0 +1,24 @@

+

+HOST:=boot2docker

+

+makescript:

+	./parsedocs.sh > make_certs.sh

+

+build: clean makescript

+	docker build -t makecerts .

+

+cert: build

+	docker run --rm -it -v $(CURDIR):/data -e HOST=$(HOST) -e YOUR_PUBLIC_IP=$(shell ip a | grep "inet " | sed "s/.*inet \([0-9.]*\)\/.*/\1/" | xargs echo | sed "s/ /,IP:/g") makecerts

+

+certs: cert

+

+run:

+	sudo docker daemon -D --tlsverify --tlscacert=ca.pem --tlscert=server-cert.pem --tlskey=server-key.pem -H=0.0.0.0:6666 --pidfile=$(pwd)/docker.pid --graph=$(pwd)/graph

+

+client:

+	sudo docker --tls --tlscacert=ca.pem --tlscert=cert.pem --tlskey=key.pem   -H=$(HOST):6666 version

+	sudo docker --tlsverify --tlscacert=ca.pem --tlscert=cert.pem --tlskey=key.pem   -H=$(HOST):6666 info

+	sudo curl https://$(HOST):6666/images/json --cert ./cert.pem --key ./key.pem --cacert ./ca.pem

+

+clean:

+	rm -f ca-key.pem ca.pem ca.srl cert.pem client.csr extfile.cnf key.pem server-cert.pem server-key.pem server.csr extfile.cnf

new file mode 100644

@@ -0,0 +1,32 @@

+<!--[metadata]>

+draft = true

+<![end-metadata]-->

+

+

+

+This is an initial attempt to make it easier to test the examples in the https.md

+doc

+

+at this point, it has to be a manual thing, and I've been running it in boot2docker

+

+so my process is

+

+$ boot2docker ssh

+$$ git clone https://github.com/docker/docker

+$$ cd docker/docs/articles/https

+$$ make cert

+lots of things to see and manually answer, as openssl wants to be interactive

+**NOTE:** make sure you enter the hostname (`boot2docker` in my case) when prompted for `Computer Name`)

+$$ sudo make run

+

+start another terminal

+

+$ boot2docker ssh

+$$ cd docker/docs/articles/https

+$$ make client

+

+the last will connect first with `--tls` and then with `--tlsverify`

+

+both should succeed

new file mode 100755

@@ -0,0 +1,23 @@

+#!/bin/sh

+openssl genrsa -aes256 -out ca-key.pem 2048

+openssl req -new -x509 -days 365 -key ca-key.pem -sha256 -out ca.pem

+openssl genrsa -out server-key.pem 2048

+openssl req -subj "/CN=$HOST" -new -key server-key.pem -out server.csr

+echo subjectAltName = IP:$YOUR_PUBLIC_IP > extfile.cnf

+openssl x509 -req -days 365 -in server.csr -CA ca.pem -CAkey ca-key.pem       -CAcreateserial -out server-cert.pem -extfile extfile.cnf

+openssl genrsa -out key.pem 2048

+openssl req -subj '/CN=client' -new -key key.pem -out client.csr

+echo extendedKeyUsage = clientAuth > extfile.cnf

+openssl x509 -req -days 365 -in client.csr -CA ca.pem -CAkey ca-key.pem       -CAcreateserial -out cert.pem -extfile extfile.cnf

+rm -v client.csr server.csr

+chmod -v 0400 ca-key.pem key.pem server-key.pem

+chmod -v 0444 ca.pem server-cert.pem cert.pem

+# docker -d --tlsverify --tlscacert=ca.pem --tlscert=server-cert.pem --tlskey=server-key.pem       -H=0.0.0.0:7778

+# docker --tlsverify --tlscacert=ca.pem --tlscert=cert.pem --tlskey=key.pem       -H=$HOST:7778 version

+mkdir -pv ~/.docker

+cp -v {ca,cert,key}.pem ~/.docker

+export DOCKER_HOST=tcp://$HOST:7778 DOCKER_TLS_VERIFY=1

+# docker ps

+export DOCKER_CERT_PATH=~/.docker/zone1/

+# docker --tlsverify ps

+# curl https://$HOST:7778/images/json       --cert ~/.docker/cert.pem       --key ~/.docker/key.pem       --cacert ~/.docker/ca.pem

new file mode 100755

@@ -0,0 +1,10 @@

+#!/bin/sh

+

+echo "#!/bin/sh"

+cat ../https.md | awk '{if (sub(/\\$/,"")) printf "%s", $0; else print $0}' \

+        | grep '   $ ' \

+        | sed 's/    $ //g' \

+        | sed 's/2375/7777/g' \

+        | sed 's/2376/7778/g' \

+        | sed 's/^docker/# docker/g' \

+        | sed 's/^curl/# curl/g'

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

@@ -5,6 +5,7 @@ description = "Enabling seccomp in Docker"

 keywords = ["seccomp, security, docker, documentation"]

 [menu.main]

 parent= "smn_secure_docker"

+weight=90

 +++

 <![end-metadata]-->

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

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

-