diff --git a/engine/security/trust/content_trust.md b/engine/security/trust/content_trust.md index 1be9699fa0..ac52662f41 100644 --- a/engine/security/trust/content_trust.md +++ b/engine/security/trust/content_trust.md @@ -100,8 +100,7 @@ read how to [manage keys for DCT](trust_key_mng.md). ## Signing Images with Docker Content Trust > **Note:** -> This applies to Docker Community Engine 17.12 and newer, and Docker -> Enterprise Engine 18.03 and newer. +> This applies to Docker Community Engine 17.12 and newer. Within the Docker CLI we can sign and push a container image with the `$ docker trust` command syntax. This is built on top of the Notary feature @@ -213,188 +212,9 @@ Enter passphrase for signer key with ID 8ae710e: Successfully deleted signature for registry.example.com/admin/demo:1 ``` -## Runtime Enforcement with Docker Content Trust - -> **Note:** -> This only applies to Docker Enterprise Engine 18.09 or newer. This -> implementation is also separate from the `only run signed images` feature of -> [Universal Control Plane](/ee/ucp/admin/configure/run-only-the-images-you-trust/) - -Docker Content Trust within the Docker Enterprise Engine prevents a user from -using a container image from an unknown source, it will also prevent a user from -building a container image from a base layer from an unknown source. Trusted -sources could include Official Docker Images, found on the [Docker -Hub](https://hub.docker.com/search?image_filter=official&type=image), or User -trusted sources, with repositories and tags signed with the commands [above](#signing-images-with-docker-content-trust). - -Engine Signature Verification prevents the following: -* `$ docker container run` of an unsigned or altered image. -* `$ docker pull` of an unsigned or altered image. -* `$ docker build` where the `FROM` image is not signed or is not scratch. - -> **Note:** -> The implicit pulls and runs performed by worker -> nodes for a [Swarm service](../../swarm/services.md) on `$ docker service create` and -> `$ docker service update` are also verified. Tag resolution of services -> requires that all nodes in the Swarm including managers have content trust -> enabled and similarly configured. - -DCT does not verify that a running container’s filesystem has not been altered -from what was in the image. For example, it does not prevent a container from -writing to the filesystem, once the container is running. Moreover, it does not -prevent the image's filesystem from being altered on a docker host's disk. DCT -will also not prevent unsigned images from being imported, loaded, or created. - -### Enabling DCT within the Docker Enterprise Engine - -DCT is controlled by the Docker Engine's configuration file. By default this is -found at `/etc/docker/daemon.json`. More details on this file can be found -[here](/engine/reference/commandline/dockerd/#daemon-configuration-file). - -> **Note:** -> This configuration can be set on Linux machines **only**. - -The `content-trust` flag is based around a `mode` variable instructing -the engine whether to enforce signed images, and a `trust-pinning` variable -instructing the engine which sources to trust. - -`Mode` can take three variables: - -* `Disabled` - Verification is not active and the remainder of the content-trust -related metadata will be ignored. This is the default value if `mode` is not -specified. -* `Permissive` - Verification will be performed, but only failures will be -logged and remain unenforced. This configuration is intended for testing of -changes related to content-trust. The results of the signature verification -is displayed in the Docker Engine's daemon logs. -* `Enforced` - Content trust will be enforced and an image that cannot be -verified successfully will not be pulled or run. - -``` -{ - "content-trust": { - "mode": "enforced" - } -} -``` - -### Official Docker images - -All official Docker library images found on the Docker Hub (docker.io/library/*) -are signed by the same Notary root key. This root key's ID has been embedded -inside of the Docker Enterprise Engine. Therefore, to enforce that, only official -Docker images can be used. Specify: - -``` -{ - "content-trust": { - "trust-pinning": { - "official-library-images": true - }, - "mode": "enforced" - } -} -``` - -### User-Signed images - -There are two options for trust pinning user-signed images: - -* Notary Canonical Root Key ID (DCT Root Key) is an ID that describes *just* the -root key used to sign a repository (or rather its respective keys). This is the -root key on the host that originally signed the repository (i.e. your workstation). -This can be retrieved from the workstation that signed the repository through -`$ grep -r "root" ~/.docker/trust/private/` (Assuming your trust data is -at `~/.docker/trust/*`). It is expected that this canonical ID has initiated -multiple image repositories (`mydtr/user1/image1` and `mydtr/user1/image2`). - -``` -# Retrieving Root ID -$ grep -r "root" ~/.docker/trust/private -/home/ubuntu/.docker/trust/private/0b6101527b2ac766702e4b40aa2391805b70e5031c04714c748f914e89014403.key:role: root - -# Using a Canonical ID that has signed 2 repos (mydtr/user1/repo1 and mydtr/user1/repo2). Note you can use a Wildcard. - -{ - "content-trust": { - "trust-pinning": { - "root-keys": { - "mydtr/user1/*": [ - "0b6101527b2ac766702e4b40aa2391805b70e5031c04714c748f914e89014403" - ] - } - }, - "mode": "enforced" - } -} -``` - -* Notary Root key ID (DCT Certificate ID) is an ID that describes the same, but -the ID is unique per repository. For example, `mydtr/user1/image1` and `mydtr/usr1/image2` -will have unique certificate IDs. A certificate ID can be retrieved through a -`$ docker trust inspect` command and is labelled as a root-key (referring back -to the Notary key name). This is designed for when different users are signing -their own repositories, for example, when there is no central signing server. As a cert-id -is more granular, it would take priority if a conflict occurs over a root ID. - -``` -# Retrieving Cert ID -$ docker trust inspect mydtr/user1/repo1 | jq -r '.[].AdministrativeKeys[] | select(.Name=="Root") | .Keys[].ID' -9430d6e31e3b3e240957a1b62bbc2d436aafa33726d0fcb50addbf7e2dfa2168 - -# Using Cert Ids, by specifying 2 repositories by their DCT root ID. Example for using this may be different DTRs or maybe because the repository was initiated on different hosts, therefore having different canonical IDs. - -{ - "content-trust": { - "trust-pinning": { - "cert-ids": { - "mydtr/user1/repo1": [ - "9430d6e31e3b3e240957a1b62bbc2d436aafa33726d0fcb50addbf7e2dfa2168" - ], - "mydtr/user2/repo1": [ - "544cf09f294860f9d5bc953ad80b386063357fd206b37b541bb2c54166f38d08" - ] - } - }, - "mode": "enforced" - } -} -``` - -### Using DCT in an offline environment - -If your engine is unable to communicate to the registry, we can enable DCT to -trust cached signature data. This is done through the -`allow-expired-cached-trust-data` variable. - -``` -{ - "content-trust": { - "trust-pinning": { - "official-library-images": true, - "root-keys": { - "mydtr/user1/*": [ - "0b6101527b2ac766702e4b40aa2391805b70e5031c04714c748f914e89014403" - ] - }, - "cert-ids": { - "mydtr/user2/repo1": [ - "9430d6e31e3b3e240957a1b62bbc2d436aafa33726d0fcb50addbf7e2dfa2168" - ], - } - }, - "mode": "enforced", - "allow-expired-cached-trust-data": true - } -} -``` - ## Client Enforcement with Docker Content Trust -> Note this is supported on Docker Community and Enterprise Engines newer than -> 17.03. - -Currently, content trust is disabled by default in the Docker Client. To enable +Content trust is disabled by default in the Docker Client. To enable it, set the `DOCKER_CONTENT_TRUST` environment variable to `1`. This prevents users from working with tagged images unless they contain a signature. diff --git a/notary/getting_started.md b/notary/getting_started.md index 036d88123c..5ffddf2f2a 100644 --- a/notary/getting_started.md +++ b/notary/getting_started.md @@ -8,8 +8,6 @@ This document describes basic use of the Notary CLI as a tool supporting Docker Content Trust. For more advanced use cases, you must [run your own Notary service](running_a_service.md). Read the [use the Notary client for advanced users](advanced_usage.md) documentation. -> **Warning**: Assistance with the open-source notary client or server is not provided by -Docker Enterprise Customer Support.