From 77da3bcb72ba4f936c428cb2b912c007a94cb87a Mon Sep 17 00:00:00 2001 From: Riyaz Faizullabhoy Date: Wed, 20 Apr 2016 23:05:44 -0700 Subject: [PATCH] Update DCT docs with 1.11 info, fix typos Signed-off-by: Riyaz Faizullabhoy --- docs/security/trust/content_trust.md | 21 +++++++++------------ docs/security/trust/deploying_notary.md | 2 +- docs/security/trust/trust_automation.md | 4 ++-- docs/security/trust/trust_delegation.md | 4 ++-- docs/security/trust/trust_key_mng.md | 12 +++++++++++- 5 files changed, 25 insertions(+), 18 deletions(-) diff --git a/docs/security/trust/content_trust.md b/docs/security/trust/content_trust.md index f11e4e6ef7..98b06fdd77 100644 --- a/docs/security/trust/content_trust.md +++ b/docs/security/trust/content_trust.md @@ -13,15 +13,11 @@ weight=-1 When transferring data among networked systems, *trust* is a central concern. In particular, when communicating over an untrusted medium such as the internet, it -is critical to ensure the integrity and publisher of all the data a system -operates on. You use Docker to push and pull images (data) to a registry. Content trust -gives you the ability to both verify the integrity and the publisher of all the +is critical to ensure the integrity and the publisher of all the data a system +operates on. You use Docker Engine to push and pull images (data) to a public or private registry. Content trust +gives you the ability to verify both the integrity and the publisher of all the data received from a registry over any channel. -Content trust is currently only available for users of the public Docker Hub. It -is currently not available for the Docker Trusted Registry or for private -registries. - ## Understand trust in Docker Content trust allows operations with a remote Docker registry to enforce @@ -82,7 +78,7 @@ desirable, unsigned image tags are "invisible" to them. ![Trust view](images/trust_view.png) -To the consumer who does not enabled content trust, nothing about how they +To the consumer who has not enabled content trust, nothing about how they work with Docker images changes. Every image is visible regardless of whether it is signed or not. @@ -127,7 +123,7 @@ The following image depicts the various signing keys and their relationships: >tag from this repository prior to the loss. You should backup the root key somewhere safe. Given that it is only required -to create new repositories, it is a good idea to store it offline. +to create new repositories, it is a good idea to store it offline in hardware. For details on securing, and backing up your keys, make sure you read how to [manage keys for content trust](trust_key_mng.md). @@ -198,11 +194,12 @@ When you push your first tagged image with content trust enabled, the `docker` client recognizes this is your first push and: - alerts you that it will create a new root key - - requests a passphrase for the key + - requests a passphrase for the root key - generates a root key in the `~/.docker/trust` directory + - requests a passphrase for the repository key - generates a repository key for in the `~/.docker/trust` directory -The passphrase you chose for both the root key and your content key-pair +The passphrase you chose for both the root key and your repository key-pair should be randomly generated and stored in a *password manager*. > **NOTE**: If you omit the `latest` tag, content trust is skipped. This is true @@ -267,7 +264,7 @@ Because the tag `docker/cliffs:latest` is not trusted, the `pull` fails. ### Disable content trust for specific operations -A user that wants to disable content trust for a particular operation can use the +A user who wants to disable content trust for a particular operation can use the `--disable-content-trust` flag. **Warning: this flag disables content trust for this operation**. With this flag, Docker will ignore content-trust and allow all operations to be done without verifying any signatures. If we wanted the diff --git a/docs/security/trust/deploying_notary.md b/docs/security/trust/deploying_notary.md index 68e57fb794..9da685f42e 100644 --- a/docs/security/trust/deploying_notary.md +++ b/docs/security/trust/deploying_notary.md @@ -21,7 +21,7 @@ The easiest way to deploy Notary Server is by using Docker Compose. To follow th docker-compose up -d - For more detailed documentation about how to deploy Notary Server see https://github.com/docker/notary. + For more detailed documentation about how to deploy Notary Server see the [instructions to run a Notary service](/notary/running_a_service.md) as well as https://github.com/docker/notary for more information. 3. Make sure that your Docker or Notary client trusts Notary Server's certificate before you try to interact with the Notary server. See the instructions for [Docker](../../reference/commandline/cli.md#notary) or diff --git a/docs/security/trust/trust_automation.md b/docs/security/trust/trust_automation.md index 1b3d4564f0..74c17f5cfb 100644 --- a/docs/security/trust/trust_automation.md +++ b/docs/security/trust/trust_automation.md @@ -10,7 +10,7 @@ parent= "smn_content_trust" # Automation with content trust -Your automation systems that pull or build images can also work with trust. Any automation environment must set `DOCKER_TRUST_ENABLED` either manually or in in a scripted fashion before processing images. +Your automation systems that pull or build images can also work with trust. Any automation environment must set `DOCKER_TRUST_ENABLED` either manually or in a scripted fashion before processing images. ## Bypass requests for passphrases @@ -43,7 +43,7 @@ Signing and pushing trust metadata ## Building with content trust -You can also build with content trust. Before running the `docker build` command, you should set the environment variable `DOCKER_CONTENT_TRUST` either manually or in in a scripted fashion. Consider the simple Dockerfile below. +You can also build with content trust. Before running the `docker build` command, you should set the environment variable `DOCKER_CONTENT_TRUST` either manually or in a scripted fashion. Consider the simple Dockerfile below. ```Dockerfile FROM docker/trusttest:latest diff --git a/docs/security/trust/trust_delegation.md b/docs/security/trust/trust_delegation.md index ac803bc9f1..050d14e67e 100644 --- a/docs/security/trust/trust_delegation.md +++ b/docs/security/trust/trust_delegation.md @@ -18,7 +18,7 @@ sharing your repository key (a combination of your targets and snapshot keys - please see "[Manage keys for content trust](trust_key_mng.md)" for more information). A collaborator can keep their own delegation key private. -The `targest/releases` delegation is currently an optional feature - in order +The `targets/releases` delegation is currently an optional feature - in order to set up delegations, you must use the Notary CLI: 1. [Download the client](https://github.com/docker/notary/releases) and ensure that it is @@ -40,7 +40,7 @@ available on your path For more detailed information about how to use Notary outside of the default Docker Content Trust use cases, please refer to the -[the Notary CLI documentation](https://docs.docker.com/notary/getting_started/). +[the Notary CLI documentation](/notary/getting_started.md). Note that when publishing and listing delegation changes using the Notary client, your Docker Hub credentials are required. diff --git a/docs/security/trust/trust_key_mng.md b/docs/security/trust/trust_key_mng.md index c15b84bacc..b74feadebf 100644 --- a/docs/security/trust/trust_key_mng.md +++ b/docs/security/trust/trust_key_mng.md @@ -37,7 +37,7 @@ workflow. They need to be Note: Prior to Docker Engine 1.11, the snapshot key was also generated and stored locally client-side. [Use the Notary CLI to manage your snapshot key locally -again](https://docs.docker.com/notary/advanced_usage/#rotate-keys) for +again](/notary/advanced_usage.md#rotate-keys) for repositories created with newer versions of Docker. ## Choosing a passphrase @@ -64,6 +64,16 @@ Before backing them up, you should `tar` them into an archive: $ umask 077; tar -zcvf private_keys_backup.tar.gz ~/.docker/trust/private; umask 022 ``` +## Hardware storage and signing + +Docker Content Trust can store and sign with root keys from a Yubikey 4. The +Yubikey is prioritized over keys stored in the filesystem. When you initialize a +new repository with content trust, Docker Engine looks for a root key locally. If a +key is not found and the Yubikey 4 exists, Docker Engine creates a root key in the +Yubikey 4. Please consult the [Notary documentation](/notary/advanced_usage.md#use-a-yubikey) for more details. + +Prior to Docker Engine 1.11, this feature was only in the experimental branch. + ## Lost keys If a publisher loses keys it means losing the ability to sign trusted content for