docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Clarifying use of flag 

Updating with Seb's comments
Updating with comments from review

Signed-off-by: Mary Anthony <mary@docker.com>
This commit is contained in:
Mary Anthony 2015-09-13 13:22:04 -07:00
parent 552c361f39
commit a2f545c86d
1 changed files with 59 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

108
docs/security/trust/content_trust.md
View File

@ -16,19 +16,19 @@ 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 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 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 gives you the ability to both verify the integrity and the publisher of all the
data received from a registry over any channel. data received from a registry over any channel.
Content trust is currently only available for users of the public Docker Hub. It 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 is currently not available for the Docker Trusted Registry or for private
registries. registries.
## Understand trust in Docker ## Understand trust in Docker
Content trust allows operations with a remote Docker registry to enforce Content trust allows operations with a remote Docker registry to enforce
client-side signing and verification of image tags. Content trust provides the client-side signing and verification of image tags. Content trust provides the
ability to use digital signatures for data sent to and received from remote ability to use digital signatures for data sent to and received from remote
Docker registries. These signatures allow client-side verification of the Docker registries. These signatures allow client-side verification of the
integrity and publisher of specific image tags. integrity and publisher of specific image tags.
Currently, content trust is disabled by default. You must enabled it by setting Currently, content trust is disabled by default. You must enabled it by setting
the `DOCKER_CONTENT_TRUST` environment variable. the `DOCKER_CONTENT_TRUST` environment variable.
@ -36,7 +36,7 @@ the `DOCKER_CONTENT_TRUST` environment variable.
Once content trust is enabled, image publishers can sign their images. Image consumers can Once content trust is enabled, image publishers can sign their images. Image consumers can
ensure that the images they use are signed. publishers and consumers can be ensure that the images they use are signed. publishers and consumers can be
individuals alone or in organizations. Docker's content trust supports users and individuals alone or in organizations. Docker's content trust supports users and
automated processes such as builds. automated processes such as builds.
### Image tags and content trust ### Image tags and content trust
@ -48,7 +48,7 @@ An individual image record has the following identifier:
A particular image `REPOSITORY` can have multiple tags. For example, `latest` and A particular image `REPOSITORY` can have multiple tags. For example, `latest` and
`3.1.2` are both tags on the `mongo` image. An image publisher can build an image `3.1.2` are both tags on the `mongo` image. An image publisher can build an image
and tag combination many times changing the image with each build. and tag combination many times changing the image with each build.
Content trust is associated with the `TAG` portion of an image. Each image Content trust is associated with the `TAG` portion of an image. Each image
repository has a set of keys that image publishers use to sign an image tag. repository has a set of keys that image publishers use to sign an image tag.
@ -67,7 +67,7 @@ Publishers can choose to sign a specific tag or not. As a result, the content of
an unsigned tag and that of a signed tag with the same name may not match. For an unsigned tag and that of a signed tag with the same name may not match. For
example, a publisher can push a tagged image `someimage:latest` and sign it. example, a publisher can push a tagged image `someimage:latest` and sign it.
Later, the same publisher can push an unsigned `someimage:latest` image. This second Later, the same publisher can push an unsigned `someimage:latest` image. This second
push replaces the last unsigned tag `latest` but does not affect the signed `latest` version. push replaces the last unsigned tag `latest` but does not affect the signed `latest` version.
The ability to choose which tags they can sign, allows publishers to iterate over The ability to choose which tags they can sign, allows publishers to iterate over
the unsigned version of an image before officially signing it. the unsigned version of an image before officially signing it.
@ -92,9 +92,9 @@ operate with content trust are:
* `push` * `push`
* `build` * `build`
* `create` * `create`
* `pull` * `pull`
* `run` * `run`
For example, with content trust enabled a `docker pull someimage:latest` only For example, with content trust enabled a `docker pull someimage:latest` only
succeeds if `someimage:latest` is signed. However, an operation with an explicit succeeds if `someimage:latest` is signed. However, an operation with an explicit
@ -105,7 +105,7 @@ $ docker pull someimage@sha256:d149ab53f8718e987c3a3024bb8aa0e2caadf6c0328f1d9d8
``` ```
Trust for an image tag is managed through the use of signing keys. Docker's content Trust for an image tag is managed through the use of signing keys. Docker's content
trust makes use four different keys: trust makes use four different keys:
| Key | Description | | Key | Description |
|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------| |---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
@ -126,25 +126,25 @@ The following image depicts the various signing keys and their relationships:
>Correcting this loss requires intervention from [Docker >Correcting this loss requires intervention from [Docker
>Support](https://support.docker.com) to reset the repository state. This loss >Support](https://support.docker.com) to reset the repository state. This loss
>also requires **manual intervention** from every consumer that used a signed >also requires **manual intervention** from every consumer that used a signed
>tag from this repository prior to the loss. >tag from this repository prior to the loss.
You should backup the offline key somewhere safe. Given that it is only required You should backup the offline key somewhere safe. Given that it is only required
to create new repositories, it is a good idea to store it offline. Make sure you to create new repositories, it is a good idea to store it offline. Make sure you
read [Manage keys for content trust](/security/trust/trust_key_mng) information read [Manage keys for content trust](/security/trust/trust_key_mng) information
for details on creating, securing, and backing up your keys. for details on creating, securing, and backing up your keys.
## Survey of typical content trust operations ## Survey of typical content trust operations
This section surveys the typical trusted operations users perform with Docker This section surveys the typical trusted operations users perform with Docker
images. images.
### Enable content trust ### Enable and disable content trust per-shell or per-invocation
Enable content trust by setting the `DOCKER_CONTENT_TRUST` environment variable. In a shell, you can enable content trust by setting the `DOCKER_CONTENT_TRUST`
Enabling per-shell is useful because you can have one shell configured for environment variable. Enabling per-shell is useful because you can have one
trusted operations and another terminal shell for untrusted operations. You can shell configured for trusted operations and another terminal shell for untrusted
also add this declaration to your shell profile to have it turned on always by operations. You can also add this declaration to your shell profile to have it
default. turned on always by default.
To enable content trust in a `bash` shell enter the following command: To enable content trust in a `bash` shell enter the following command:
@ -152,23 +152,36 @@ To enable content trust in a `bash` shell enter the following command:
export DOCKER_CONTENT_TRUST=1 export DOCKER_CONTENT_TRUST=1
``` ```
Once set, each of the "tag" operations require key for trusted tag. All of these Once set, each of the "tag" operations requires a key for a trusted tag.
commands also support the `--disable-content-trust` flag. This flag allows
publishers to run individual operations on tagged images without content trust on an In an environment where `DOCKER_CONTENT_TRUST` is set, you can use the
as-needed basis. `--disable-content-trust` flag to run individual operations on tagged images
without content trust on an as-needed basis.
```bash
$ docker pull --disable-content-trust docker/trusttest:untrusted
```
To invoke a command with content trust enabled regardless of whether or how the `DOCKER_CONTENT_TRUST` variable is set:
```bash
$ docker build --disable-content-trust=false -t docker/trusttest:testing .
```
All of the trusted operations support the `--disable-content-trust` flag.
### Push trusted content ### Push trusted content
To create signed content for a specific image tag, simply enable content trust and push To create signed content for a specific image tag, simply enable content trust
a tagged image. If this is the first time you have pushed an image using content trust and push a tagged image. If this is the first time you have pushed an image
on your system, the session looks like this: using content trust on your system, the session looks like this:
```bash ```bash
$ docker push docker/trusttest:latest $ docker push docker/trusttest:latest
The push refers to a repository [docker.io/docker/trusttest] (len: 1) The push refers to a repository [docker.io/docker/trusttest] (len: 1)
9a61b6b1315e: Image already exists 9a61b6b1315e: Image already exists
902b87aaaec9: Image already exists 902b87aaaec9: Image already exists
latest: digest: sha256:d02adacee0ac7a5be140adb94fa1dae64f4e71a68696e7f8e7cbf9db8dd49418 size: 3220 latest: digest: sha256:d02adacee0ac7a5be140adb94fa1dae64f4e71a68696e7f8e7cbf9db8dd49418 size: 3220
Signing and pushing trust metadata Signing and pushing trust metadata
You are about to create a new offline signing key passphrase. This passphrase You are about to create a new offline signing key passphrase. This passphrase
@ -177,31 +190,31 @@ 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 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 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. way to recover this key. You can find the key in your config directory.
Enter passphrase for new offline key with id a1d96fb: Enter passphrase for new offline key with id a1d96fb:
Repeat passphrase for new offline key with id a1d96fb: Repeat passphrase for new offline key with id a1d96fb:
Enter passphrase for new tagging key with id docker.io/docker/trusttest (3a932f1): Enter passphrase for new tagging key with id docker.io/docker/trusttest (3a932f1):
Repeat passphrase for new tagging key with id docker.io/docker/trusttest (3a932f1): Repeat passphrase for new tagging key with id docker.io/docker/trusttest (3a932f1):
Finished initializing "docker.io/docker/trusttest" Finished initializing "docker.io/docker/trusttest"
``` ```
When you push your first tagged image with content trust enabled, the `docker` client When you push your first tagged image with content trust enabled, the `docker`
recognizes this is your first push and: client recognizes this is your first push and:
- alerts you that it will create a new offline key - alerts you that it will create a new offline key
- requests a passphrase for the key - requests a passphrase for the key
- generates an offline key in the `~/.docker/trust` directory - generates an offline key in the `~/.docker/trust` directory
- generates a tagging key for in the `~/.docker/trust` directory - generates a tagging key for in the `~/.docker/trust` directory
The passphrase you chose for both the offline key and your content key-pair should
be randomly generated and stored in a *password manager*.
It is important to note, if you had left off the `latest` tag, content trust is skipped. The passphrase you chose for both the offline key and your content key-pair
This is true even if content trust is enabled and even if this is your first push. should be randomly generated and stored in a *password manager*.
> **NOTE**: If you omit the `latest` tag, content trust is skipped. This is true
even if content trust is enabled and even if this is your first push.
```bash ```bash
$ docker push docker/trusttest $ docker push docker/trusttest
The push refers to a repository [docker.io/docker/trusttest] (len: 1) The push refers to a repository [docker.io/docker/trusttest] (len: 1)
9a61b6b1315e: Image successfully pushed 9a61b6b1315e: Image successfully pushed
902b87aaaec9: Image successfully pushed 902b87aaaec9: Image successfully pushed
latest: digest: sha256:a9a9c4402604b703bed1c847f6d85faac97686e48c579bd9c3b0fa6694a398fc size: 3220 latest: digest: sha256:a9a9c4402604b703bed1c847f6d85faac97686e48c579bd9c3b0fa6694a398fc size: 3220
No tag specified, skipping trust metadata push No tag specified, skipping trust metadata push
``` ```
@ -215,13 +228,13 @@ you create can use that same offline key:
```bash ```bash
$ docker push docker.io/docker/seaside:latest $ docker push docker.io/docker/seaside:latest
The push refers to a repository [docker.io/docker/seaside] (len: 1) The push refers to a repository [docker.io/docker/seaside] (len: 1)
a9539b34a6ab: Image successfully pushed a9539b34a6ab: Image successfully pushed
b3dbab3810fc: Image successfully pushed b3dbab3810fc: Image successfully pushed
latest: digest: sha256:d2ba1e603661a59940bfad7072eba698b79a8b20ccbb4e3bfb6f9e367ea43939 size: 3346 latest: digest: sha256:d2ba1e603661a59940bfad7072eba698b79a8b20ccbb4e3bfb6f9e367ea43939 size: 3346
Signing and pushing trust metadata Signing and pushing trust metadata
Enter key passphrase for offline key with id a1d96fb: Enter key passphrase for offline key with id a1d96fb:
Enter passphrase for new tagging key with id docker.io/docker/seaside (bb045e3): Enter passphrase for new tagging key with id docker.io/docker/seaside (bb045e3):
Repeat passphrase for new tagging key with id docker.io/docker/seaside (bb045e3): Repeat passphrase for new tagging key with id docker.io/docker/seaside (bb045e3):
Finished initializing "docker.io/docker/seaside" Finished initializing "docker.io/docker/seaside"
``` ```
@ -232,7 +245,7 @@ these.
### Pull image content ### Pull image content
A common way to consume an image is to `pull` it. With content trust enabled, the Docker A common way to consume an image is to `pull` it. With content trust enabled, the Docker
client only allows `docker pull` to retrieve signed images. client only allows `docker pull` to retrieve signed images.
``` ```
$ docker pull docker/seaside $ docker pull docker/seaside
@ -286,6 +299,3 @@ $ docker push --disable-content-trust docker/trusttest:untrusted
* [Manage keys for content trust](/security/trust/trust_key_mng) * [Manage keys for content trust](/security/trust/trust_key_mng)
* [Automation with content trust](/security/trust/trust_automation) * [Automation with content trust](/security/trust/trust_automation)
* [Play in a content trust sandbox](/security/trust/trust_sandbox) * [Play in a content trust sandbox](/security/trust/trust_sandbox)