diff options
Diffstat (limited to 'devdocs/docker/engine%2Fsecurity%2Ftrust%2Ftrust_sandbox%2Findex.html')
| -rw-r--r-- | devdocs/docker/engine%2Fsecurity%2Ftrust%2Ftrust_sandbox%2Findex.html | 123 |
1 files changed, 123 insertions, 0 deletions
diff --git a/devdocs/docker/engine%2Fsecurity%2Ftrust%2Ftrust_sandbox%2Findex.html b/devdocs/docker/engine%2Fsecurity%2Ftrust%2Ftrust_sandbox%2Findex.html new file mode 100644 index 00000000..fa22410c --- /dev/null +++ b/devdocs/docker/engine%2Fsecurity%2Ftrust%2Ftrust_sandbox%2Findex.html @@ -0,0 +1,123 @@ +<h1>Play in a content trust sandbox</h1> + +<p>This page explains how to set up and use a sandbox for experimenting with trust. The sandbox allows you to configure and try trust operations locally without impacting your production images.</p> <p>Before working through this sandbox, you should have read through the <a href="../index">trust overview</a>.</p> <h3 id="prerequisites">Prerequisites</h3> <p>These instructions assume you are running in Linux or macOS. You can run this sandbox on a local machine or on a virtual machine. You need to have privileges to run docker commands on your local machine or in the VM.</p> <p>This sandbox requires you to install two Docker tools: Docker Engine >= 1.10.0 and Docker Compose >= 1.6.0. To install the Docker Engine, choose from the <a href="../../../install/index">list of supported platforms</a>. To install Docker Compose, see the <a href="../../../../compose/install/index">detailed instructions here</a>.</p> <h2 id="what-is-in-the-sandbox">What is in the sandbox?</h2> <p>If you are just using trust out-of-the-box you only need your Docker Engine client and access to the Docker Hub. The sandbox mimics a production trust environment, and sets up these additional components.</p> <table> <thead> <tr> <th>Container</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td>trustsandbox</td> <td>A container with the latest version of Docker Engine and with some preconfigured certificates. This is your sandbox where you can use the <code class="language-plaintext highlighter-rouge">docker</code> client to test trust operations.</td> </tr> <tr> <td>Registry server</td> <td>A local registry service.</td> </tr> <tr> <td>Notary server</td> <td>The service that does all the heavy-lifting of managing trust</td> </tr> </tbody> </table> <p>This means you run your own content trust (Notary) server and registry. If you work exclusively with the Docker Hub, you would not need these components. They are built into the Docker Hub for you. For the sandbox, however, you build your own entire, mock production environment.</p> <p>Within the <code class="language-plaintext highlighter-rouge">trustsandbox</code> container, you interact with your local registry rather than the Docker Hub. This means your everyday image repositories are not used. They are protected while you play.</p> <p>When you play in the sandbox, you also create root and repository keys. The sandbox is configured to store all the keys and files inside the <code class="language-plaintext highlighter-rouge">trustsandbox</code> container. Since the keys you create in the sandbox are for play only, destroying the container destroys them as well.</p> <p>By using a docker-in-docker image for the <code class="language-plaintext highlighter-rouge">trustsandbox</code> container, you also don’t pollute your real Docker daemon cache with any images you push and pull. The images are stored in an anonymous volume attached to this container, and can be destroyed after you destroy the container.</p> <h2 id="build-the-sandbox">Build the sandbox</h2> <p>In this section, you use Docker Compose to specify how to set up and link together the <code class="language-plaintext highlighter-rouge">trustsandbox</code> container, the Notary server, and the Registry server.</p> <ol> <li> <p>Create a new <code class="language-plaintext highlighter-rouge">trustsandbox</code> directory and change into it.</p> <div class="highlight"><pre class="highlight" data-language=""> $ mkdir trustsandbox + $ cd trustsandbox +</pre></div> </li> <li> <p>Create a file called <code class="language-plaintext highlighter-rouge">docker-compose.yml</code> with your favorite editor. For example, using vim:</p> <div class="highlight"><pre class="highlight" data-language=""> $ touch docker-compose.yml + $ vim docker-compose.yml +</pre></div> </li> <li> <p>Add the following to the new file.</p> <div class="highlight"><pre class="highlight" data-language=""> version: "2" + services: + notaryserver: + image: dockersecurity/notary_autobuilds:server-v0.5.1 + volumes: + - notarycerts:/var/lib/notary/fixtures + networks: + - sandbox + environment: + - NOTARY_SERVER_STORAGE_TYPE=memory + - NOTARY_SERVER_TRUST_SERVICE_TYPE=local + sandboxregistry: + image: registry:2.4.1 + networks: + - sandbox + container_name: sandboxregistry + trustsandbox: + image: docker:dind + networks: + - sandbox + volumes: + - notarycerts:/notarycerts + privileged: true + container_name: trustsandbox + entrypoint: "" + command: |- + sh -c ' + cp /notarycerts/root-ca.crt /usr/local/share/ca-certificates/root-ca.crt && + update-ca-certificates && + dockerd-entrypoint.sh --insecure-registry sandboxregistry:5000' + volumes: + notarycerts: + external: false + networks: + sandbox: + external: false +</pre></div> </li> <li> <p>Save and close the file.</p> </li> <li> <p>Run the containers on your local system.</p> <div class="highlight"><pre class="highlight" data-language=""> $ docker-compose up -d +</pre></div> <p>The first time you run this, the docker-in-docker, Notary server, and registry images are downloaded from Docker Hub.</p> </li> </ol> <h2 id="play-in-the-sandbox">Play in the sandbox</h2> <p>Now that everything is setup, you can go into your <code class="language-plaintext highlighter-rouge">trustsandbox</code> container and start testing Docker content trust. From your host machine, obtain a shell in the <code class="language-plaintext highlighter-rouge">trustsandbox</code> container.</p> <div class="highlight"><pre class="highlight" data-language="">$ docker container exec -it trustsandbox sh +/ # +</pre></div> <h3 id="test-some-trust-operations">Test some trust operations</h3> <p>Now, pull some images from within the <code class="language-plaintext highlighter-rouge">trustsandbox</code> container.</p> <ol> <li> <p>Download a <code class="language-plaintext highlighter-rouge">docker</code> image to test with.</p> <div class="highlight"><pre class="highlight" data-language=""> / # docker pull docker/trusttest + docker pull docker/trusttest + Using default tag: latest + latest: Pulling from docker/trusttest + + b3dbab3810fc: Pull complete + a9539b34a6ab: Pull complete + Digest: sha256:d149ab53f8718e987c3a3024bb8aa0e2caadf6c0328f1d9d850b2a2a67f2819a + Status: Downloaded newer image for docker/trusttest:latest +</pre></div> </li> <li> <p>Tag it to be pushed to our sandbox registry:</p> <div class="highlight"><pre class="highlight" data-language=""> / # docker tag docker/trusttest sandboxregistry:5000/test/trusttest:latest +</pre></div> </li> <li> <p>Enable content trust.</p> <div class="highlight"><pre class="highlight" data-language=""> / # export DOCKER_CONTENT_TRUST=1 +</pre></div> </li> <li> <p>Identify the trust server.</p> <div class="highlight"><pre class="highlight" data-language=""> / # export DOCKER_CONTENT_TRUST_SERVER=https://notaryserver:4443 +</pre></div> <p>This step is only necessary because the sandbox is using its own server. Normally, if you are using the Docker Public Hub this step isn’t necessary.</p> </li> <li> <p>Pull the test image.</p> <div class="highlight"><pre class="highlight" data-language=""> / # docker pull sandboxregistry:5000/test/trusttest + Using default tag: latest + Error: remote trust data does not exist for sandboxregistry:5000/test/trusttest: notaryserver:4443 does not have trust data for sandboxregistry:5000/test/trusttest +</pre></div> <p>You see an error, because this content doesn’t exist on the <code class="language-plaintext highlighter-rouge">notaryserver</code> yet.</p> </li> <li> <p>Push and sign the trusted image.</p> <div class="highlight"><pre class="highlight" data-language=""> / # docker push sandboxregistry:5000/test/trusttest:latest + The push refers to a repository [sandboxregistry:5000/test/trusttest] + 5f70bf18a086: Pushed + c22f7bc058a9: Pushed + latest: digest: sha256:ebf59c538accdf160ef435f1a19938ab8c0d6bd96aef8d4ddd1b379edf15a926 size: 734 + Signing and pushing trust metadata + You are about to create a new root signing key passphrase. This passphrase + will be used to protect the most sensitive key in your signing system. Please + choose a long, complex passphrase and be careful to keep the password and the + key file itself secure and backed up. It is highly recommended that you use a + password manager to generate the passphrase and keep it safe. There will be no + way to recover this key. You can find the key in your config directory. + Enter passphrase for new root key with ID 27ec255: + Repeat passphrase for new root key with ID 27ec255: + Enter passphrase for new repository key with ID 58233f9 (sandboxregistry:5000/test/trusttest): + Repeat passphrase for new repository key with ID 58233f9 (sandboxregistry:5000/test/trusttest): + Finished initializing "sandboxregistry:5000/test/trusttest" + Successfully signed "sandboxregistry:5000/test/trusttest":latest +</pre></div> <p>Because you are pushing this repository for the first time, Docker creates new root and repository keys and asks you for passphrases with which to encrypt them. If you push again after this, it only asks you for repository passphrase so it can decrypt the key and sign again.</p> </li> <li> <p>Try pulling the image you just pushed:</p> <div class="highlight"><pre class="highlight" data-language=""> / # docker pull sandboxregistry:5000/test/trusttest + Using default tag: latest + Pull (1 of 1): sandboxregistry:5000/test/trusttest:latest@sha256:ebf59c538accdf160ef435f1a19938ab8c0d6bd96aef8d4ddd1b379edf15a926 + sha256:ebf59c538accdf160ef435f1a19938ab8c0d6bd96aef8d4ddd1b379edf15a926: Pulling from test/trusttest + Digest: sha256:ebf59c538accdf160ef435f1a19938ab8c0d6bd96aef8d4ddd1b379edf15a926 + Status: Downloaded newer image for sandboxregistry:5000/test/trusttest@sha256:ebf59c538accdf160ef435f1a19938ab8c0d6bd96aef8d4ddd1b379edf15a926 + Tagging sandboxregistry:5000/test/trusttest@sha256:ebf59c538accdf160ef435f1a19938ab8c0d6bd96aef8d4ddd1b379edf15a926 as sandboxregistry:5000/test/trusttest:latest +</pre></div> </li> </ol> <h3 id="test-with-malicious-images">Test with malicious images</h3> <p>What happens when data is corrupted and you try to pull it when trust is enabled? In this section, you go into the <code class="language-plaintext highlighter-rouge">sandboxregistry</code> and tamper with some data. Then, you try and pull it.</p> <ol> <li> <p>Leave the <code class="language-plaintext highlighter-rouge">trustsandbox</code> shell and container running.</p> </li> <li> <p>Open a new interactive terminal from your host, and obtain a shell into the <code class="language-plaintext highlighter-rouge">sandboxregistry</code> container.</p> <div class="highlight"><pre class="highlight" data-language="">$ docker container exec -it sandboxregistry bash +root@65084fc6f047:/# +</pre></div> </li> <li> <p>List the layers for the <code class="language-plaintext highlighter-rouge">test/trusttest</code> image you pushed:</p> <div class="highlight"><pre class="highlight" data-language="">root@65084fc6f047:/# ls -l /var/lib/registry/docker/registry/v2/repositories/test/trusttest/_layers/sha256 +total 12 +drwxr-xr-x 2 root root 4096 Jun 10 17:26 a3ed95caeb02ffe68cdd9fd84406680ae93d633cb16422d00e8a7c22955b46d4 +drwxr-xr-x 2 root root 4096 Jun 10 17:26 aac0c133338db2b18ff054943cee3267fe50c75cdee969aed88b1992539ed042 +drwxr-xr-x 2 root root 4096 Jun 10 17:26 cc7629d1331a7362b5e5126beb5bf15ca0bf67eb41eab994c719a45de53255cd +</pre></div> </li> <li> <p>Change into the registry storage for one of those layers (this is in a different directory):</p> <div class="highlight"><pre class="highlight" data-language="">root@65084fc6f047:/# cd /var/lib/registry/docker/registry/v2/blobs/sha256/aa/aac0c133338db2b18ff054943cee3267fe50c75cdee969aed88b1992539ed042 +</pre></div> </li> <li> <p>Add malicious data to one of the <code class="language-plaintext highlighter-rouge">trusttest</code> layers:</p> <div class="highlight"><pre class="highlight" data-language="">root@65084fc6f047:/# echo "Malicious data" > data +</pre></div> </li> <li> <p>Go back to your <code class="language-plaintext highlighter-rouge">trustsandbox</code> terminal.</p> </li> <li> <p>List the <code class="language-plaintext highlighter-rouge">trusttest</code> image.</p> <div class="highlight"><pre class="highlight" data-language="">/ # docker image ls | grep trusttest +REPOSITORY TAG IMAGE ID CREATED SIZE +docker/trusttest latest cc7629d1331a 11 months ago 5.025 MB +sandboxregistry:5000/test/trusttest latest cc7629d1331a 11 months ago 5.025 MB +sandboxregistry:5000/test/trusttest <none> cc7629d1331a 11 months ago 5.025 MB +</pre></div> </li> <li> <p>Remove the <code class="language-plaintext highlighter-rouge">trusttest:latest</code> image from our local cache.</p> <div class="highlight"><pre class="highlight" data-language="">/ # docker image rm -f cc7629d1331a +Untagged: docker/trusttest:latest +Untagged: sandboxregistry:5000/test/trusttest:latest +Untagged: sandboxregistry:5000/test/trusttest@sha256:ebf59c538accdf160ef435f1a19938ab8c0d6bd96aef8d4ddd1b379edf15a926 +Deleted: sha256:cc7629d1331a7362b5e5126beb5bf15ca0bf67eb41eab994c719a45de53255cd +Deleted: sha256:2a1f6535dc6816ffadcdbe20590045e6cbf048d63fd4cc753a684c9bc01abeea +Deleted: sha256:c22f7bc058a9a8ffeb32989b5d3338787e73855bf224af7aa162823da015d44c +</pre></div> <p>Docker does not re-download images that it already has cached, but we want Docker to attempt to download the tampered image from the registry and reject it because it is invalid.</p> </li> <li> <p>Pull the image again. This downloads the image from the registry, because we don’t have it cached.</p> <div class="highlight"><pre class="highlight" data-language="">/ # docker pull sandboxregistry:5000/test/trusttest +Using default tag: latest +Pull (1 of 1): sandboxregistry:5000/test/trusttest:latest@sha256:35d5bc26fd358da8320c137784fe590d8fcf9417263ef261653e8e1c7f15672e +sha256:35d5bc26fd358da8320c137784fe590d8fcf9417263ef261653e8e1c7f15672e: Pulling from test/trusttest + +aac0c133338d: Retrying in 5 seconds +a3ed95caeb02: Download complete +error pulling image configuration: unexpected EOF +</pre></div> <p>The pull did not complete because the trust system couldn’t verify the image.</p> </li> </ol> <h2 id="more-play-in-the-sandbox">More play in the sandbox</h2> <p>Now, you have a full Docker content trust sandbox on your local system, feel free to play with it and see how it behaves. If you find any security issues with Docker, feel free to send us an email at <a href="mailto:security@docker.com">security@docker.com</a>.</p> <h2 id="clean-up-your-sandbox">Clean up your sandbox</h2> <p>When you are done, and want to clean up all the services you’ve started and any anonymous volumes that have been created, just run the following command in the directory where you’ve created your Docker Compose file:</p> <div class="highlight"><pre class="highlight" data-language=""> $ docker-compose down -v +</pre></div> +<p><a href="https://docs.docker.com/search/?q=trust">trust</a>, <a href="https://docs.docker.com/search/?q=security">security</a>, <a href="https://docs.docker.com/search/?q=root">root</a>, <a href="https://docs.docker.com/search/?q=keys">keys</a>, <a href="https://docs.docker.com/search/?q=repository">repository</a>, <a href="https://docs.docker.com/search/?q=sandbox">sandbox</a></p> +<div class="_attribution"> + <p class="_attribution-p"> + © 2019 Docker, Inc.<br>Licensed under the Apache License, Version 2.0.<br>Docker and the Docker logo are trademarks or registered trademarks of Docker, Inc. in the United States and/or other countries.<br>Docker, Inc. and other parties may also have trademark rights in other terms used herein.<br> + <a href="https://docs.docker.com/engine/security/trust/trust_sandbox/" class="_attribution-link">https://docs.docker.com/engine/security/trust/trust_sandbox/</a> + </p> +</div> |