From 6e00f1eb82d8d93e7fb1ab7f8891824f6136d3f3 Mon Sep 17 00:00:00 2001 From: Anne Henmi Date: Tue, 16 Oct 2018 19:15:32 -0600 Subject: [PATCH 01/21] Initial blurb on engine signature verification --- engine/security/security.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/engine/security/security.md b/engine/security/security.md index d524ca85ed..7ec9feaf33 100644 --- a/engine/security/security.md +++ b/engine/security/security.md @@ -199,6 +199,13 @@ capability removal, or less secure through the addition of capabilities. The best practice for users would be to remove all capabilities except those explicitly required for their processes. +## Dockert Content Trust Signature Verification + +The Docker Engine can be configured to only permitted to run signed +images. This is configured in the Dockerd configuration file. To +incorporate this, Docker will use trustpinning. Trustpinning means Docker +reposoitories with a known configured root key will only be accepted. + ## Other kernel security features Capabilities are just one of the many security features provided by From 15a8fcd60bf7eb9e05373582f6a274cbb4611bb4 Mon Sep 17 00:00:00 2001 From: Anne Henmi Date: Tue, 16 Oct 2018 19:22:22 -0600 Subject: [PATCH 02/21] Added x-ref. --- engine/security/security.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/engine/security/security.md b/engine/security/security.md index 7ec9feaf33..b42a538f53 100644 --- a/engine/security/security.md +++ b/engine/security/security.md @@ -199,12 +199,16 @@ capability removal, or less secure through the addition of capabilities. The best practice for users would be to remove all capabilities except those explicitly required for their processes. -## Dockert Content Trust Signature Verification +## Docker Content Trust Signature Verification -The Docker Engine can be configured to only permitted to run signed -images. This is configured in the Dockerd configuration file. To -incorporate this, Docker will use trustpinning. Trustpinning means Docker -reposoitories with a known configured root key will only be accepted. +The Docker Content Trust signature verification feature is built directly +into the `dockerd` binary. The Docker Engine can be configured to only +permitted to run signed images. This is configured in the Dockerd +configuration file. To incorporate this, Docker will use trustpinning. +Trustpinning means Docker reposoitories with a known configured root key +will only be accepted. + +For more information on configuring Docker Content Trust Signature Verificiation, go to (xxx)[xxx]. ## Other kernel security features From ddc2bb4e115c353bbb7f12c2c8a4853fe073e3ef Mon Sep 17 00:00:00 2001 From: Anne Henmi Date: Tue, 16 Oct 2018 19:23:32 -0600 Subject: [PATCH 03/21] Added x-ref --- engine/security/security.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/engine/security/security.md b/engine/security/security.md index b42a538f53..6e030d314c 100644 --- a/engine/security/security.md +++ b/engine/security/security.md @@ -208,7 +208,7 @@ configuration file. To incorporate this, Docker will use trustpinning. Trustpinning means Docker reposoitories with a known configured root key will only be accepted. -For more information on configuring Docker Content Trust Signature Verificiation, go to (xxx)[xxx]. +For more information on configuring Docker Content Trust Signature Verificiation, go to (sxxx)[xxx]. ## Other kernel security features From 1155d5322551b58a26e4495558a4a5661423c89c Mon Sep 17 00:00:00 2001 From: Anne Henmi Date: Tue, 16 Oct 2018 19:32:03 -0600 Subject: [PATCH 04/21] Testing rebase. --- engine/security/security.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/engine/security/security.md b/engine/security/security.md index 6e030d314c..b42a538f53 100644 --- a/engine/security/security.md +++ b/engine/security/security.md @@ -208,7 +208,7 @@ configuration file. To incorporate this, Docker will use trustpinning. Trustpinning means Docker reposoitories with a known configured root key will only be accepted. -For more information on configuring Docker Content Trust Signature Verificiation, go to (sxxx)[xxx]. +For more information on configuring Docker Content Trust Signature Verificiation, go to (xxx)[xxx]. ## Other kernel security features From bf9ed86856da25ab41f328716a4e2de092515095 Mon Sep 17 00:00:00 2001 From: Anne Henmi Date: Tue, 16 Oct 2018 19:50:20 -0600 Subject: [PATCH 05/21] Added more explanation, cleaned up wording. --- engine/security/security.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/engine/security/security.md b/engine/security/security.md index b42a538f53..74124d004f 100644 --- a/engine/security/security.md +++ b/engine/security/security.md @@ -204,9 +204,14 @@ those explicitly required for their processes. The Docker Content Trust signature verification feature is built directly into the `dockerd` binary. The Docker Engine can be configured to only permitted to run signed images. This is configured in the Dockerd -configuration file. To incorporate this, Docker will use trustpinning. -Trustpinning means Docker reposoitories with a known configured root key -will only be accepted. +configuration file. To incorporate this, the Docker engine have +trustpinning configured in the `daemon.json` file. Trustpinning is when +Docker reposoitories with a known configured root key will only be accepted. + +This feature provides image signature verification whenever a Docker pull +or run command uses an image. This provides insight to administrators that +was not previously available with the CLI being responsible for enforcing +and performing image signature verification. For more information on configuring Docker Content Trust Signature Verificiation, go to (xxx)[xxx]. From 6f8524d5fce4dc8f536dc30b8b0351f395bd651d Mon Sep 17 00:00:00 2001 From: Anne Henmi Date: Wed, 17 Oct 2018 08:48:40 -0600 Subject: [PATCH 06/21] Started working on the detailed content for the DCT plugin. --- engine/security/trust/content_trust.md | 71 ++++++++++++++++++++++---- 1 file changed, 62 insertions(+), 9 deletions(-) diff --git a/engine/security/trust/content_trust.md b/engine/security/trust/content_trust.md index a2e5f972a3..aa977a70f9 100644 --- a/engine/security/trust/content_trust.md +++ b/engine/security/trust/content_trust.md @@ -25,16 +25,35 @@ the `DOCKER_CONTENT_TRUST` environment variable to `1`. Refer to the and [Notary](../../reference/commandline/cli.md#notary) configuration for the docker client for more options. -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 -individuals alone or in organizations. Docker's content trust supports users and -automated processes such as builds. +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 individuals alone or in organizations. Docker's content trust supports users and automated processes such as builds. When you enable content trust, signing occurs on the client after push and verification happens on the client after pull if you use Docker CE. If you use Docker EE with UCP, and you have configured UCP to require images to be signed before deploying, signing is verified by UCP. +To enforce Docker to run only signed images, configure the `daemon.json` file: + +``` +{ + ... + “content-trust”: { + “trust-pinning”: { + “root-keys”: { + “myregistry.com/myorg/*”: [“keyID1”, “keyID2”], + “myregistry.com/otherorg/repo”: [“keyID3”] + }, + “official-images”: true, + }, + “skip-check-on-run”: true, + “allow-expired-trust-cache”: true, + } +} + +``` + +xxx - add configuration table here or xref- xxx + ### Image tags and content trust An individual image record has the following identifier: @@ -139,13 +158,47 @@ these various trusted operations: * Pull the signed image pushed above * Pull unsigned image pushed above +### Enabling Content Trust in Docker Engine Configuration + +The signature verification feature is configured in the Docker daemon configuration file `daemon.json`. + +``` +{ + ... + “content-trust”: { + “trust-pinning”: { + “root-keys”: { + “myregistry.com/myorg/*”: [“keyID1”, “keyID2”], + “myregistry.com/otherorg/repo”: [“keyID3”] + }, + “official-images”: true, + }, + “skip-check-on-run”: true, + “allow-expired-trust-cache”: true, + } +} +``` + +| Stanza | Description | +| ----------------------- |:-------------:| +| trust-pinning:root-keys |A mapping of image globs to root key IDs which should have signed the root metadata of the image trust data. These key IDs are canonical IDs; root keys in DCT are certificates tying the name of the image to the repo metadata, so each one’s ID is different per repo. The ID of the private key (the canonical key ID) corresponding to the certificate though is the same no matter what the name of the mage. + +If this setting is provided, any image not matching one of these globs will not be trusted at all (with the optional exception of official images - see below) + +If an image’s name matches more than one glob, then the most specific (longest) one is chosen. + +***Note:*** the Docker Trust CLI or some other tool needs to be able to provide these canonical key IDs, +as opposed to just the regular key IDs | + ### Enable and disable content trust per-shell or per-invocation -In a shell, you can enable content trust by setting the `DOCKER_CONTENT_TRUST` -environment variable. Enabling per-shell is useful because you can have one -shell configured for trusted operations and another terminal shell for untrusted -operations. You can also add this declaration to your shell profile to have it -turned on always by default. +Instead of enabling Docker Content Trust through the system-wide configuration, Docker +Content Trust can be enabled or disabled on a per-shell or per-invocation basis. + +To enable on a per-shell basis, enable the `DOCKER_CONTENT_TRUST` environment variable. +Enabling per-shell is useful because you can have one shell configured for trusted operations +and another terminal shell for untrusted operations. You can also add this declaration to +your shell profile to have it turned on always by default. To enable content trust in a `bash` shell enter the following command: From e7202bbfc46866c58185a9dc1b6c7dab22e2ce14 Mon Sep 17 00:00:00 2001 From: Anne Henmi Date: Wed, 17 Oct 2018 08:50:17 -0600 Subject: [PATCH 07/21] Fixed table column --- engine/security/trust/content_trust.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/engine/security/trust/content_trust.md b/engine/security/trust/content_trust.md index aa977a70f9..7bb72b4e2d 100644 --- a/engine/security/trust/content_trust.md +++ b/engine/security/trust/content_trust.md @@ -180,7 +180,7 @@ The signature verification feature is configured in the Docker daemon configurat ``` | Stanza | Description | -| ----------------------- |:-------------:| +| ----------------------- |:--------------| | trust-pinning:root-keys |A mapping of image globs to root key IDs which should have signed the root metadata of the image trust data. These key IDs are canonical IDs; root keys in DCT are certificates tying the name of the image to the repo metadata, so each one’s ID is different per repo. The ID of the private key (the canonical key ID) corresponding to the certificate though is the same no matter what the name of the mage. If this setting is provided, any image not matching one of these globs will not be trusted at all (with the optional exception of official images - see below) From c9296ab1c92a9ba0c3859807100970820ba4e69e Mon Sep 17 00:00:00 2001 From: Anne Henmi Date: Wed, 17 Oct 2018 08:53:05 -0600 Subject: [PATCH 08/21] fixed table, again. --- engine/security/trust/content_trust.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/engine/security/trust/content_trust.md b/engine/security/trust/content_trust.md index 7bb72b4e2d..96d9450011 100644 --- a/engine/security/trust/content_trust.md +++ b/engine/security/trust/content_trust.md @@ -180,7 +180,7 @@ The signature verification feature is configured in the Docker daemon configurat ``` | Stanza | Description | -| ----------------------- |:--------------| +| ----------------------- |---------------| | trust-pinning:root-keys |A mapping of image globs to root key IDs which should have signed the root metadata of the image trust data. These key IDs are canonical IDs; root keys in DCT are certificates tying the name of the image to the repo metadata, so each one’s ID is different per repo. The ID of the private key (the canonical key ID) corresponding to the certificate though is the same no matter what the name of the mage. If this setting is provided, any image not matching one of these globs will not be trusted at all (with the optional exception of official images - see below) From 1ba6e4f414304ef0c585e046944935143e2d6834 Mon Sep 17 00:00:00 2001 From: Anne Henmi Date: Wed, 17 Oct 2018 09:00:03 -0600 Subject: [PATCH 09/21] Fixed formatting, added another row for testing before completing table. --- engine/security/trust/content_trust.md | 57 +++++++++++--------------- 1 file changed, 23 insertions(+), 34 deletions(-) diff --git a/engine/security/trust/content_trust.md b/engine/security/trust/content_trust.md index 96d9450011..5e56d9c367 100644 --- a/engine/security/trust/content_trust.md +++ b/engine/security/trust/content_trust.md @@ -19,41 +19,11 @@ ability to use digital signatures for data sent to and received from remote Docker registries. These signatures allow client-side verification of the integrity and publisher of specific image tags. -Currently, content trust is disabled by default. To enable it, set -the `DOCKER_CONTENT_TRUST` environment variable to `1`. Refer to the -[environment variables](../../reference/commandline/cli.md#environment-variables) -and [Notary](../../reference/commandline/cli.md#notary) configuration -for the docker client for more options. - -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 individuals alone or in organizations. Docker's content trust supports users and automated processes such as builds. - When you enable content trust, signing occurs on the client after push and verification happens on the client after pull if you use Docker CE. If you use Docker EE with UCP, and you have configured UCP to require images to be signed before deploying, signing is verified by UCP. -To enforce Docker to run only signed images, configure the `daemon.json` file: - -``` -{ - ... - “content-trust”: { - “trust-pinning”: { - “root-keys”: { - “myregistry.com/myorg/*”: [“keyID1”, “keyID2”], - “myregistry.com/otherorg/repo”: [“keyID3”] - }, - “official-images”: true, - }, - “skip-check-on-run”: true, - “allow-expired-trust-cache”: true, - } -} - -``` - -xxx - add configuration table here or xref- xxx - ### Image tags and content trust An individual image record has the following identifier: @@ -160,7 +130,20 @@ these various trusted operations: ### Enabling Content Trust in Docker Engine Configuration -The signature verification feature is configured in the Docker daemon configuration file `daemon.json`. +Currently, content trust is disabled by default. To enable it, set +the `DOCKER_CONTENT_TRUST` environment variable to `1`. Refer to the +[environment variables](../../reference/commandline/cli.md#environment-variables) +and [Notary](../../reference/commandline/cli.md#notary) configuration +for the docker client for more options. + +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 individuals +alone or in organizations. Docker's content trust supports users and automated processes +such as builds. + + +The signature verification feature is configured in the Docker daemon configuration file +`daemon.json`. ``` { @@ -179,16 +162,22 @@ The signature verification feature is configured in the Docker daemon configurat } ``` -| Stanza | Description | +| ***Stanza*** | ***Description*** | | ----------------------- |---------------| -| trust-pinning:root-keys |A mapping of image globs to root key IDs which should have signed the root metadata of the image trust data. These key IDs are canonical IDs; root keys in DCT are certificates tying the name of the image to the repo metadata, so each one’s ID is different per repo. The ID of the private key (the canonical key ID) corresponding to the certificate though is the same no matter what the name of the mage. +| `trust-pinning:root-keys` |A mapping of image globs to root key IDs which should have signed the root metadata of the image trust data. These key IDs are canonical IDs; root keys in DCT are certificates tying the name of the image to the repo metadata, so each one’s ID is different per repo. The ID of the private key (the canonical key ID) corresponding to the certificate though is the same no matter what the name of the mage. If this setting is provided, any image not matching one of these globs will not be trusted at all (with the optional exception of official images - see below) If an image’s name matches more than one glob, then the most specific (longest) one is chosen. - ***Note:*** the Docker Trust CLI or some other tool needs to be able to provide these canonical key IDs, as opposed to just the regular key IDs | +|`trust-pinning:library-images` | +Docker EE will have the docker official images root key ID hard-coded. If this option is turned on, users will not have to look up the key ID of the Docker official library images (excluding DTR/UCP) and include it in their `trust-pinning:root-keys` setting - this will pin the official libraries (`docker.io/library/*`) to that hard-coded root key, and the official images will be trusted by default in addition to whatever images are specified by `trust-pinning:root-keys`. + +Certified images from Docker Store and DTR/UCP would be considered for a future feature. + +If `trustpinning:root-keys` specifies a key mapping for `docker.io/library/*`, those keys will be preferred for trust pinning. Otherwise, if a more general `docker.io/*` or `*` are specified, the official images key will be preferred.| + ### Enable and disable content trust per-shell or per-invocation From 3397e5129cd4db0d408e4a911baec6e55acc43c6 Mon Sep 17 00:00:00 2001 From: Anne Henmi Date: Wed, 17 Oct 2018 09:02:23 -0600 Subject: [PATCH 10/21] More table formatting fun. --- engine/security/trust/content_trust.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/engine/security/trust/content_trust.md b/engine/security/trust/content_trust.md index 5e56d9c367..fca3553022 100644 --- a/engine/security/trust/content_trust.md +++ b/engine/security/trust/content_trust.md @@ -170,13 +170,13 @@ If this setting is provided, any image not matching one of these globs will not If an image’s name matches more than one glob, then the most specific (longest) one is chosen. ***Note:*** the Docker Trust CLI or some other tool needs to be able to provide these canonical key IDs, -as opposed to just the regular key IDs | +as opposed to just the regular key IDs | |`trust-pinning:library-images` | Docker EE will have the docker official images root key ID hard-coded. If this option is turned on, users will not have to look up the key ID of the Docker official library images (excluding DTR/UCP) and include it in their `trust-pinning:root-keys` setting - this will pin the official libraries (`docker.io/library/*`) to that hard-coded root key, and the official images will be trusted by default in addition to whatever images are specified by `trust-pinning:root-keys`. Certified images from Docker Store and DTR/UCP would be considered for a future feature. -If `trustpinning:root-keys` specifies a key mapping for `docker.io/library/*`, those keys will be preferred for trust pinning. Otherwise, if a more general `docker.io/*` or `*` are specified, the official images key will be preferred.| +If `trustpinning:root-keys` specifies a key mapping for `docker.io/library/*`, those keys will be preferred for trust pinning. Otherwise, if a more general `docker.io/*` or `*` are specified, the official images key will be preferred. | ### Enable and disable content trust per-shell or per-invocation From f415a1de99ce6f388d688be5f87f39d4833df02d Mon Sep 17 00:00:00 2001 From: Anne Henmi Date: Thu, 18 Oct 2018 09:43:45 -0600 Subject: [PATCH 11/21] Fixed formatting, cleaning up text a bit. --- engine/security/trust/content_trust.md | 13 ++++--------- 1 file changed, 4 insertions(+), 9 deletions(-) diff --git a/engine/security/trust/content_trust.md b/engine/security/trust/content_trust.md index fca3553022..16a2e67f2a 100644 --- a/engine/security/trust/content_trust.md +++ b/engine/security/trust/content_trust.md @@ -164,19 +164,14 @@ The signature verification feature is configured in the Docker daemon configurat | ***Stanza*** | ***Description*** | | ----------------------- |---------------| -| `trust-pinning:root-keys` |A mapping of image globs to root key IDs which should have signed the root metadata of the image trust data. These key IDs are canonical IDs; root keys in DCT are certificates tying the name of the image to the repo metadata, so each one’s ID is different per repo. The ID of the private key (the canonical key ID) corresponding to the certificate though is the same no matter what the name of the mage. - -If this setting is provided, any image not matching one of these globs will not be trusted at all (with the optional exception of official images - see below) - +| `trust-pinning:root-keys` |A mapping of image globs to root key IDs which should have signed the root metadata of the image trust data. These key IDs are canonical IDs; root keys in DCT are certificates tying the name of the image to the repo metadata, so each one’s ID is different per repo. The ID of the private key (the canonical key ID) corresponding to the certificate though is the same no matter what the name of the mage.
+If this setting is provided, any image not matching one of these globs will not be trusted at all (with the optional exception of official images - see below)
If an image’s name matches more than one glob, then the most specific (longest) one is chosen. ***Note:*** the Docker Trust CLI or some other tool needs to be able to provide these canonical key IDs, as opposed to just the regular key IDs | |`trust-pinning:library-images` | -Docker EE will have the docker official images root key ID hard-coded. If this option is turned on, users will not have to look up the key ID of the Docker official library images (excluding DTR/UCP) and include it in their `trust-pinning:root-keys` setting - this will pin the official libraries (`docker.io/library/*`) to that hard-coded root key, and the official images will be trusted by default in addition to whatever images are specified by `trust-pinning:root-keys`. - -Certified images from Docker Store and DTR/UCP would be considered for a future feature. - -If `trustpinning:root-keys` specifies a key mapping for `docker.io/library/*`, those keys will be preferred for trust pinning. Otherwise, if a more general `docker.io/*` or `*` are specified, the official images key will be preferred. | +Docker EE will have the docker official images root key ID hard-coded. If this option is turned on, users will not have to look up the key ID of the Docker official library images (excluding DTR/UCP) and include it in their `trust-pinning:root-keys` setting - this will pin the official libraries (`docker.io/library/*`) to that hard-coded root key, and the official images will be trusted by default in addition to whatever images are specified by `trust-pinning:root-keys`.
+If `trustpinning:root-keys` specifies a key mapping for `docker.io/library/*`, those keys will be preferred for trust pinning. Otherwise, if a more general `docker.io/*` or `*` are specified, the official images key will be preferred.
| ### Enable and disable content trust per-shell or per-invocation From ea19cdbe08c2afe49917a228e3c9358561803ce1 Mon Sep 17 00:00:00 2001 From: Anne Henmi Date: Thu, 18 Oct 2018 09:47:34 -0600 Subject: [PATCH 12/21] More table fun. --- engine/security/trust/content_trust.md | 11 ++--------- 1 file changed, 2 insertions(+), 9 deletions(-) diff --git a/engine/security/trust/content_trust.md b/engine/security/trust/content_trust.md index 16a2e67f2a..7e4bd53e5c 100644 --- a/engine/security/trust/content_trust.md +++ b/engine/security/trust/content_trust.md @@ -164,15 +164,8 @@ The signature verification feature is configured in the Docker daemon configurat | ***Stanza*** | ***Description*** | | ----------------------- |---------------| -| `trust-pinning:root-keys` |A mapping of image globs to root key IDs which should have signed the root metadata of the image trust data. These key IDs are canonical IDs; root keys in DCT are certificates tying the name of the image to the repo metadata, so each one’s ID is different per repo. The ID of the private key (the canonical key ID) corresponding to the certificate though is the same no matter what the name of the mage.
-If this setting is provided, any image not matching one of these globs will not be trusted at all (with the optional exception of official images - see below)
-If an image’s name matches more than one glob, then the most specific (longest) one is chosen. -***Note:*** the Docker Trust CLI or some other tool needs to be able to provide these canonical key IDs, -as opposed to just the regular key IDs | -|`trust-pinning:library-images` | -Docker EE will have the docker official images root key ID hard-coded. If this option is turned on, users will not have to look up the key ID of the Docker official library images (excluding DTR/UCP) and include it in their `trust-pinning:root-keys` setting - this will pin the official libraries (`docker.io/library/*`) to that hard-coded root key, and the official images will be trusted by default in addition to whatever images are specified by `trust-pinning:root-keys`.
-If `trustpinning:root-keys` specifies a key mapping for `docker.io/library/*`, those keys will be preferred for trust pinning. Otherwise, if a more general `docker.io/*` or `*` are specified, the official images key will be preferred.
| - +| `trust-pinning:root-keys` | A mapping of image globs to root key IDs which should have signed the root metadata of the image trust data. These key IDs are canonical IDs; root keys in DCT are certificates tying the name of the image to the repo metadata, so each one’s ID is different per repo. The ID of the private key (the canonical key ID) corresponding to the certificate though is the same no matter what the name of the image.
If this setting is provided, any image not matching one of these globs will not be trusted at all (with the optional exception of official images - see below)
If an image’s name matches more than one glob, then the most specific (longest) one is chosen. ***Note:*** the Docker Trust CLI or some other tool needs to be able to provide these canonical key IDs, as opposed to just the regular key IDs| +|`trust-pinning:library-images` | Docker EE will have the docker official images root key ID hard-coded. If this option is turned on, users will not have to look up the key ID of the Docker official library images (excluding DTR/UCP) and include it in their `trust-pinning:root-keys` setting - this will pin the official libraries (`docker.io/library/*`) to that hard-coded root key, and the official images will be trusted by default in addition to whatever images are specified by `trust-pinning:root-keys`.
If `trustpinning:root-keys` specifies a key mapping for `docker.io/library/*`, those keys will be preferred for trust pinning. Otherwise, if a more general `docker.io/*` or `*` are specified, the official images key will be preferred.
| ### Enable and disable content trust per-shell or per-invocation From bcf2835e8352f91e73be7b9bd922d4838fb69a89 Mon Sep 17 00:00:00 2001 From: Anne Henmi Date: Thu, 18 Oct 2018 10:31:18 -0600 Subject: [PATCH 13/21] Initial draft for user/dockerd/daemon.json complete. Need to check API docs before review. --- engine/security/trust/content_trust.md | 33 ++++++++++++++++++++++++-- 1 file changed, 31 insertions(+), 2 deletions(-) diff --git a/engine/security/trust/content_trust.md b/engine/security/trust/content_trust.md index 7e4bd53e5c..0584489b6c 100644 --- a/engine/security/trust/content_trust.md +++ b/engine/security/trust/content_trust.md @@ -141,6 +141,32 @@ can ensure that the images they use are signed. Publishers and consumers can be alone or in organizations. Docker's content trust supports users and automated processes such as builds. +Engine Signature Verification will prevent the following behaviors on an image: +* Running a container to build an image (the base image must be signed, or must be scratch) +* Creating a container from an image that isn’t signed +* Enabling `skip-check-on-run` allows containers created by an already existing services to use whatever image was specified starting a container from an unsigned image +* Enabling `skip-check-on-run` also allows containers previously created to run, independent of specified image + +Content trust 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, nor +the container’s filesystem from being altered on disk. + +It will also only pull signed images from registries, but will not prevent unsigned images from being +imported, loaded, or created. + +The image name, digest, or tag must be verified if content trust is enabled. he latest DCT metadata for +an image must be downloaded from the trust server associated with the registry: +* If an image tag does not have a digest, the DCT metadata translates the name to an image digest +* If an image tag has an image digest, the DCT metadata verifies that the name matches the provided digest +* If an image digest does not have an image tag, the DCT metadata reverse lookups and provides the image tag as well as the digest. + +If translation or verification fails, the request or operation requiring the image is failed. +This can happen because the content trust server is not reachable, if the `allow-expired-trust-cache` +is eanbled, or the the DCT metadata is used if the timestamp has not expired. + +Provided `skip-check-on-run` is not enabled, an initiated container's image will be re-validated +against the cached metadata first. If the cached metadata has expired or is not available, the image +will be validated using the image name, digest, or tag. The signature verification feature is configured in the Docker daemon configuration file `daemon.json`. @@ -164,8 +190,11 @@ The signature verification feature is configured in the Docker daemon configurat | ***Stanza*** | ***Description*** | | ----------------------- |---------------| -| `trust-pinning:root-keys` | A mapping of image globs to root key IDs which should have signed the root metadata of the image trust data. These key IDs are canonical IDs; root keys in DCT are certificates tying the name of the image to the repo metadata, so each one’s ID is different per repo. The ID of the private key (the canonical key ID) corresponding to the certificate though is the same no matter what the name of the image.
If this setting is provided, any image not matching one of these globs will not be trusted at all (with the optional exception of official images - see below)
If an image’s name matches more than one glob, then the most specific (longest) one is chosen. ***Note:*** the Docker Trust CLI or some other tool needs to be able to provide these canonical key IDs, as opposed to just the regular key IDs| -|`trust-pinning:library-images` | Docker EE will have the docker official images root key ID hard-coded. If this option is turned on, users will not have to look up the key ID of the Docker official library images (excluding DTR/UCP) and include it in their `trust-pinning:root-keys` setting - this will pin the official libraries (`docker.io/library/*`) to that hard-coded root key, and the official images will be trusted by default in addition to whatever images are specified by `trust-pinning:root-keys`.
If `trustpinning:root-keys` specifies a key mapping for `docker.io/library/*`, those keys will be preferred for trust pinning. Otherwise, if a more general `docker.io/*` or `*` are specified, the official images key will be preferred.
| +| `trust-pinning:root-keys` | Root key IDs are canonical IDs that sign the root metadata of the image trust data. In Docker Certified Trust (DCT), the root keys are unique certificates tying the name of the image to the repo metadata.  The private key ID (the canonical key ID) corresponding to the certificate is not dependent on the image name. If an image’s name matches more than one glob, then the most specific (longest) one is chosen.| +|`trust-pinning:library-images` | This option pins the official libraries (`docker.io/library/*`) to the hard-coded Docker official images root key. DCT trusts the official images by default. This is in addition to whatever images are specified by `trust-pinning:root-keys`. If `trustpinning:root-keys` specifies a key mapping for `docker.io/library/*`, those keys will be preferred for trust pinning. Otherwise, if a more general `docker.io/*` or `*` are specified, the official images key will be preferred.| +| `skip-check-on-run` | Specifies whether DCT image validiation exempts existing containers or services. This determines whether the check is only on container creation or service creation, as opposed to container start or service maintenance, rescheduling, or rollback.| +| `allow-expired-trust-cache` | Specifies whether cached locally expired metadata validates images if an external server is unreachable or does not have image trust metadata. This is necessary for machines which may be often offline, as may be the case for edge. This does not provide mitigations against freeze attacks, which is a necessary to provide availability in low-connectivity environments. | + ### Enable and disable content trust per-shell or per-invocation From 506476573359275125ec49135a908167465abb68 Mon Sep 17 00:00:00 2001 From: Anne Henmi Date: Fri, 19 Oct 2018 08:09:29 -0600 Subject: [PATCH 14/21] Added more on verification. --- engine/security/trust/content_trust.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/engine/security/trust/content_trust.md b/engine/security/trust/content_trust.md index 0584489b6c..3e5cdb92d5 100644 --- a/engine/security/trust/content_trust.md +++ b/engine/security/trust/content_trust.md @@ -164,6 +164,15 @@ If translation or verification fails, the request or operation requiring the ima This can happen because the content trust server is not reachable, if the `allow-expired-trust-cache` is eanbled, or the the DCT metadata is used if the timestamp has not expired. +DCT checks against metadata, and this will prevent an image verification for happening twice when +using the `docker run` command. The `docker run` command first creates a container and starts it +immediately. + +DCT needs to verify the image because a container could have been created before a change to the +Content Trust configuration. As a result, DCT enforces the new configuration by applying it to +the old created container. Alternately, a container could have been created significantly earlier, +which means the trust data for it is no longer valid. In that case, DCT will re-verify the container. + Provided `skip-check-on-run` is not enabled, an initiated container's image will be re-validated against the cached metadata first. If the cached metadata has expired or is not available, the image will be validated using the image name, digest, or tag. From 503eb170b7834981bc4f4ad61deda1688424fbd3 Mon Sep 17 00:00:00 2001 From: Anne Henmi <41210220+ahh-docker@users.noreply.github.com> Date: Mon, 22 Oct 2018 14:56:32 -0600 Subject: [PATCH 15/21] Update security.md incorporated @jamesonhyde-docker's feedback. --- engine/security/security.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/engine/security/security.md b/engine/security/security.md index 74124d004f..00e67997b5 100644 --- a/engine/security/security.md +++ b/engine/security/security.md @@ -204,16 +204,16 @@ those explicitly required for their processes. The Docker Content Trust signature verification feature is built directly into the `dockerd` binary. The Docker Engine can be configured to only permitted to run signed images. This is configured in the Dockerd -configuration file. To incorporate this, the Docker engine have -trustpinning configured in the `daemon.json` file. Trustpinning is when -Docker reposoitories with a known configured root key will only be accepted. +configuration file. To incorporate this, the Docker Engine has +trustpinning configured in the `daemon.json` file. To enable this feature, +trustpinning can be configured in daemon.json file, whereby only repositories +signed with a user-specified root key will be allowed to be pulled and run. -This feature provides image signature verification whenever a Docker pull -or run command uses an image. This provides insight to administrators that -was not previously available with the CLI being responsible for enforcing -and performing image signature verification. +This provides insight to administrators that was not previously available with +the CLI being responsible for enforcing and performing image signature verification. -For more information on configuring Docker Content Trust Signature Verificiation, go to (xxx)[xxx]. +For more information on configuring Docker Content Trust Signature Verificiation, go to +(Content trust in Docker)[engine/security/trust/content_trust]. ## Other kernel security features From 7cc1c3955a3fd109670ce41af8faeee3befd9ee0 Mon Sep 17 00:00:00 2001 From: Anne Henmi <41210220+ahh-docker@users.noreply.github.com> Date: Mon, 22 Oct 2018 15:18:36 -0600 Subject: [PATCH 16/21] Update content_trust.md Partial incorporation of @jamesonhyde-docker's comments. Waiting for clarification on the rest. --- engine/security/trust/content_trust.md | 19 +++++++------------ 1 file changed, 7 insertions(+), 12 deletions(-) diff --git a/engine/security/trust/content_trust.md b/engine/security/trust/content_trust.md index 3e5cdb92d5..63cf67d697 100644 --- a/engine/security/trust/content_trust.md +++ b/engine/security/trust/content_trust.md @@ -143,7 +143,7 @@ such as builds. Engine Signature Verification will prevent the following behaviors on an image: * Running a container to build an image (the base image must be signed, or must be scratch) -* Creating a container from an image that isn’t signed +* Creating a container from an image that is not signed * Enabling `skip-check-on-run` allows containers created by an already existing services to use whatever image was specified starting a container from an unsigned image * Enabling `skip-check-on-run` also allows containers previously created to run, independent of specified image @@ -151,18 +151,18 @@ Content trust does not verify that a running container’s filesystem has not be was in the image. For example, it does not prevent a container from writing to the filesystem, nor the container’s filesystem from being altered on disk. -It will also only pull signed images from registries, but will not prevent unsigned images from being +It will also pull and run signed images from registries, but will not prevent unsigned images from being imported, loaded, or created. -The image name, digest, or tag must be verified if content trust is enabled. he latest DCT metadata for +The image name, digest, or tag must be verified if content trust is enabled. The latest DCT metadata for an image must be downloaded from the trust server associated with the registry: * If an image tag does not have a digest, the DCT metadata translates the name to an image digest * If an image tag has an image digest, the DCT metadata verifies that the name matches the provided digest -* If an image digest does not have an image tag, the DCT metadata reverse lookups and provides the image tag as well as the digest. +* If an image digest does not have an image tag, the DCT metadata does a reverse lookup and provides the image tag as well as the digest. If translation or verification fails, the request or operation requiring the image is failed. This can happen because the content trust server is not reachable, if the `allow-expired-trust-cache` -is eanbled, or the the DCT metadata is used if the timestamp has not expired. +is enabled, or the the DCT metadata is used if the timestamp has not expired. DCT checks against metadata, and this will prevent an image verification for happening twice when using the `docker run` command. The `docker run` command first creates a container and starts it @@ -171,11 +171,7 @@ immediately. DCT needs to verify the image because a container could have been created before a change to the Content Trust configuration. As a result, DCT enforces the new configuration by applying it to the old created container. Alternately, a container could have been created significantly earlier, -which means the trust data for it is no longer valid. In that case, DCT will re-verify the container. - -Provided `skip-check-on-run` is not enabled, an initiated container's image will be re-validated -against the cached metadata first. If the cached metadata has expired or is not available, the image -will be validated using the image name, digest, or tag. +such that the trust data for it is no longer valid. The signature verification feature is configured in the Docker daemon configuration file `daemon.json`. @@ -201,7 +197,6 @@ The signature verification feature is configured in the Docker daemon configurat | ----------------------- |---------------| | `trust-pinning:root-keys` | Root key IDs are canonical IDs that sign the root metadata of the image trust data. In Docker Certified Trust (DCT), the root keys are unique certificates tying the name of the image to the repo metadata.  The private key ID (the canonical key ID) corresponding to the certificate is not dependent on the image name. If an image’s name matches more than one glob, then the most specific (longest) one is chosen.| |`trust-pinning:library-images` | This option pins the official libraries (`docker.io/library/*`) to the hard-coded Docker official images root key. DCT trusts the official images by default. This is in addition to whatever images are specified by `trust-pinning:root-keys`. If `trustpinning:root-keys` specifies a key mapping for `docker.io/library/*`, those keys will be preferred for trust pinning. Otherwise, if a more general `docker.io/*` or `*` are specified, the official images key will be preferred.| -| `skip-check-on-run` | Specifies whether DCT image validiation exempts existing containers or services. This determines whether the check is only on container creation or service creation, as opposed to container start or service maintenance, rescheduling, or rollback.| | `allow-expired-trust-cache` | Specifies whether cached locally expired metadata validates images if an external server is unreachable or does not have image trust metadata. This is necessary for machines which may be often offline, as may be the case for edge. This does not provide mitigations against freeze attacks, which is a necessary to provide availability in low-connectivity environments. | @@ -213,7 +208,7 @@ Content Trust can be enabled or disabled on a per-shell or per-invocation basis. To enable on a per-shell basis, enable the `DOCKER_CONTENT_TRUST` environment variable. Enabling per-shell is useful because you can have one shell configured for trusted operations and another terminal shell for untrusted operations. You can also add this declaration to -your shell profile to have it turned on always by default. +your shell profile to have it enabled by default. To enable content trust in a `bash` shell enter the following command: From ee2172416fd3e9e4ee60a8e46630c4345f921117 Mon Sep 17 00:00:00 2001 From: Anne Henmi <41210220+ahh-docker@users.noreply.github.com> Date: Mon, 22 Oct 2018 16:39:25 -0600 Subject: [PATCH 17/21] Update content_trust.md --- engine/security/trust/content_trust.md | 106 ++++++++++--------------- 1 file changed, 44 insertions(+), 62 deletions(-) diff --git a/engine/security/trust/content_trust.md b/engine/security/trust/content_trust.md index 63cf67d697..c3d9db3e5e 100644 --- a/engine/security/trust/content_trust.md +++ b/engine/security/trust/content_trust.md @@ -13,18 +13,23 @@ data received from a registry over any channel. ## About trust in Docker -Content trust allows operations with a remote Docker registry to enforce -client-side signing and verification of image tags. Content trust provides the +Docker Content Trust (DCT) allows operations with a remote Docker registry to enforce +client-side signing and verification of image tags. DCT provides the ability to use digital signatures for data sent to and received from remote Docker registries. These signatures allow client-side verification of the integrity and publisher of specific image tags. -When you enable content trust, signing occurs on the client after push and +Once DCT is enabled, image publishers can sign their images. Image consumers +can ensure that the images they use are signed. Publishers and consumers can be individuals +alone or in organizations. DCT supports users and automated processes +such as builds. + +When you enable DCT, signing occurs on the client after push and verification happens on the client after pull if you use Docker CE. If you use Docker EE with UCP, and you have configured UCP to require images to be signed before deploying, signing is verified by UCP. -### Image tags and content trust +### Image tags and DCT An individual image record has the following identifier: @@ -36,7 +41,7 @@ A particular image `REPOSITORY` can have multiple tags. For example, `latest` an `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. -Content trust is associated with the `TAG` portion of an image. Each image +DCT 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. Image publishers have discretion on which tags they sign. @@ -57,24 +62,24 @@ push replaces the last unsigned tag `latest` but does not affect the signed `lat The ability to choose which tags they can sign, allows publishers to iterate over the unsigned version of an image before officially signing it. -Image consumers can enable content trust to ensure that images they use were -signed. If a consumer enables content trust, they can only pull, run, or build -with trusted images. Enabling content trust is like wearing a pair of +Image consumers can enable DCT to ensure that images they use were +signed. If a consumer enables DCT, they can only pull, run, or build +with trusted images. Enabling DCT is like wearing a pair of rose-colored glasses. Consumers "see" only signed image tags and the less desirable, unsigned image tags are "invisible" to them. ![Trust view](images/trust_view.png) -To the consumer who has not enabled content trust, nothing about how they +To the consumer who has not enabled DCT, nothing about how they work with Docker images changes. Every image is visible regardless of whether it is signed or not. -### Content trust operations and keys +### DCT operations and keys -When content trust is enabled, `docker` CLI commands that operate on tagged images must +When DCT is enabled, `docker` CLI commands that operate on tagged images must either have content signatures or explicit content hashes. The commands that -operate with content trust are: +operate with DCT are: * `push` * `build` @@ -82,7 +87,7 @@ operate with content trust are: * `pull` * `run` -For example, with content trust enabled a `docker pull someimage:latest` only +For example, with DCT enabled a `docker pull someimage:latest` only succeeds if `someimage:latest` is signed. However, an operation with an explicit content hash always succeeds as long as the hash exists: @@ -91,17 +96,17 @@ $ docker pull someimage@sha256:d149ab53f8718e987c3a3024bb8aa0e2caadf6c0328f1d9d8 ``` Trust for an image tag is managed through the use of signing keys. A key set is -created when an operation using content trust is first invoked. A key set consists +created when an operation using DCT is first invoked. A key set consists of the following classes of keys: -- an offline key that is the root of content trust for an image tag +- an offline key that is the root of DCT for an image tag - repository or tagging keys that sign tags - server-managed keys such as the timestamp key, which provides freshness security guarantees for your repository The following image depicts the various signing keys and their relationships: -![Content trust components](images/trust_components.png) +![Content Trust components](images/trust_components.png) >**WARNING**: > Loss of the root key is **very difficult** to recover from. @@ -114,9 +119,9 @@ The following image depicts the various signing keys and their relationships: 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 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). +read how to [manage keys for DCT](trust_key_mng.md). -## Survey of typical content trust operations +## Survey of typical DCT operations This section surveys the typical trusted operations users perform with Docker images. Specifically, we go through the following steps to help us exercise @@ -128,51 +133,25 @@ these various trusted operations: * Pull the signed image pushed above * Pull unsigned image pushed above -### Enabling Content Trust in Docker Engine Configuration - -Currently, content trust is disabled by default. To enable it, set -the `DOCKER_CONTENT_TRUST` environment variable to `1`. Refer to the -[environment variables](../../reference/commandline/cli.md#environment-variables) -and [Notary](../../reference/commandline/cli.md#notary) configuration -for the docker client for more options. - -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 individuals -alone or in organizations. Docker's content trust supports users and automated processes -such as builds. +### Enabling DCT in Docker Engine Configuration Engine Signature Verification will prevent the following behaviors on an image: * Running a container to build an image (the base image must be signed, or must be scratch) * Creating a container from an image that is not signed -* Enabling `skip-check-on-run` allows containers created by an already existing services to use whatever image was specified starting a container from an unsigned image -* Enabling `skip-check-on-run` also allows containers previously created to run, independent of specified image -Content trust does not verify that a running container’s filesystem has not been altered from what +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, nor the container’s filesystem from being altered on disk. It will also pull and run signed images from registries, but will not prevent unsigned images from being imported, loaded, or created. -The image name, digest, or tag must be verified if content trust is enabled. The latest DCT metadata for +The image name, digest, or tag must be verified if DCT is enabled. The latest DCT metadata for an image must be downloaded from the trust server associated with the registry: * If an image tag does not have a digest, the DCT metadata translates the name to an image digest * If an image tag has an image digest, the DCT metadata verifies that the name matches the provided digest * If an image digest does not have an image tag, the DCT metadata does a reverse lookup and provides the image tag as well as the digest. -If translation or verification fails, the request or operation requiring the image is failed. -This can happen because the content trust server is not reachable, if the `allow-expired-trust-cache` -is enabled, or the the DCT metadata is used if the timestamp has not expired. - -DCT checks against metadata, and this will prevent an image verification for happening twice when -using the `docker run` command. The `docker run` command first creates a container and starts it -immediately. - -DCT needs to verify the image because a container could have been created before a change to the -Content Trust configuration. As a result, DCT enforces the new configuration by applying it to -the old created container. Alternately, a container could have been created significantly earlier, -such that the trust data for it is no longer valid. - The signature verification feature is configured in the Docker daemon configuration file `daemon.json`. @@ -187,7 +166,7 @@ The signature verification feature is configured in the Docker daemon configurat }, “official-images”: true, }, - “skip-check-on-run”: true, + “mode”: “disabled” | “permissive” | “enforced”, “allow-expired-trust-cache”: true, } } @@ -198,19 +177,22 @@ The signature verification feature is configured in the Docker daemon configurat | `trust-pinning:root-keys` | Root key IDs are canonical IDs that sign the root metadata of the image trust data. In Docker Certified Trust (DCT), the root keys are unique certificates tying the name of the image to the repo metadata.  The private key ID (the canonical key ID) corresponding to the certificate is not dependent on the image name. If an image’s name matches more than one glob, then the most specific (longest) one is chosen.| |`trust-pinning:library-images` | This option pins the official libraries (`docker.io/library/*`) to the hard-coded Docker official images root key. DCT trusts the official images by default. This is in addition to whatever images are specified by `trust-pinning:root-keys`. If `trustpinning:root-keys` specifies a key mapping for `docker.io/library/*`, those keys will be preferred for trust pinning. Otherwise, if a more general `docker.io/*` or `*` are specified, the official images key will be preferred.| | `allow-expired-trust-cache` | Specifies whether cached locally expired metadata validates images if an external server is unreachable or does not have image trust metadata. This is necessary for machines which may be often offline, as may be the case for edge. This does not provide mitigations against freeze attacks, which is a necessary to provide availability in low-connectivity environments. | +| `mode` | Specifies whether DCT is enabled and enforced. Valid modes are:
+`disabled`: Verification is not active and the remainder of the content-trust related metadata will be ignored. *NOTE* that this is the default configuration if “mode” is not specfied.
+`permissive`: Verification will be performed, but only failures will only be logged and remain unenforced. This configuration is intended for testing of changes related to content-trust.
+`enforced`: DCT will be enforced and an image that cannot be verified successfully will not be pulled or run. | +### Enable and disable DCT per-shell or per-invocation -### Enable and disable content trust per-shell or per-invocation - -Instead of enabling Docker Content Trust through the system-wide configuration, Docker -Content Trust can be enabled or disabled on a per-shell or per-invocation basis. +Instead of enabling DCT through the system-wide configuration, DCT can be enabled or disabled +on a per-shell or per-invocation basis. To enable on a per-shell basis, enable the `DOCKER_CONTENT_TRUST` environment variable. Enabling per-shell is useful because you can have one shell configured for trusted operations and another terminal shell for untrusted operations. You can also add this declaration to your shell profile to have it enabled by default. -To enable content trust in a `bash` shell enter the following command: +To enable DCT in a `bash` shell enter the following command: ```bash export DOCKER_CONTENT_TRUST=1 @@ -220,7 +202,7 @@ Once set, each of the "tag" operations requires a key for a trusted tag. In an environment where `DOCKER_CONTENT_TRUST` is set, you can use the `--disable-content-trust` flag to run individual operations on tagged images -without content trust on an as-needed basis. +without DCT on an as-needed basis. Consider the following Dockerfile that uses an untrusted parent image: @@ -248,7 +230,7 @@ $ docker push --disable-content-trust /nottrusttest:latest ... ``` -To invoke a command with content trust enabled regardless of whether or how the `DOCKER_CONTENT_TRUST` variable is set: +To invoke a command with DCT enabled regardless of whether or how the `DOCKER_CONTENT_TRUST` variable is set: ```bash $ docker build --disable-content-trust=false -t /trusttest:testing . @@ -259,9 +241,9 @@ All of the trusted operations support the `--disable-content-trust` flag. ### Push trusted content -To create signed content for a specific image tag, simply enable content trust +To create signed content for a specific image tag, simply enable DCT and push a tagged image. If this is the first time you have pushed an image -using content trust on your system, the session looks like this: +using DCT on your system, the session looks like this: ```bash $ docker push /trusttest:testing @@ -283,7 +265,7 @@ Repeat passphrase for new repository key with id docker.io//trusttest Finished initializing "docker.io//trusttest" ``` -When you push your first tagged image with content trust enabled, the `docker` +When you push your first tagged image with DCT enabled, the `docker` client recognizes this is your first push and: - alerts you that it is creating a new root key @@ -295,8 +277,8 @@ client recognizes this is your first push and: 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 `testing` tag, content trust is skipped. This is true -even if content trust is enabled and even if this is your first push. +> **NOTE**: If you omit the `testing` tag, DCT is skipped. This is true +even if DCT is enabled and even if this is your first push. ```bash $ docker push /trusttest @@ -308,7 +290,7 @@ No tag specified, skipping trust metadata push ``` It is skipped because as the message states, you did not supply an image `TAG` -value. In Docker content trust, signatures are associated with tags. +value. In DCT, signatures are associated with tags. Once you have a root key on your system, subsequent images repositories you create can use that same root key: @@ -332,7 +314,7 @@ these. ### 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 DCT enabled, the Docker client only allows `docker pull` to retrieve signed images. Let's try to pull the image you signed and pushed earlier: From 3b86535170ef11476550e2bb81aeeca32364cc55 Mon Sep 17 00:00:00 2001 From: Anne Henmi <41210220+ahh-docker@users.noreply.github.com> Date: Thu, 25 Oct 2018 13:16:13 -0600 Subject: [PATCH 18/21] Update security.md --- engine/security/security.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/engine/security/security.md b/engine/security/security.md index 00e67997b5..cfe0655f4d 100644 --- a/engine/security/security.md +++ b/engine/security/security.md @@ -202,12 +202,10 @@ those explicitly required for their processes. ## Docker Content Trust Signature Verification The Docker Content Trust signature verification feature is built directly -into the `dockerd` binary. The Docker Engine can be configured to only -permitted to run signed images. This is configured in the Dockerd -configuration file. To incorporate this, the Docker Engine has -trustpinning configured in the `daemon.json` file. To enable this feature, -trustpinning can be configured in daemon.json file, whereby only repositories -signed with a user-specified root key will be allowed to be pulled and run. +into the `dockerd` binary. The Docker Engine can be configured to only run +signed images. This is configured in the Dockerd configuration file. +To enable this feature, trustpinning can be configured in `daemon.json`, whereby +only repositories signed with a user-specified root key can be pulled and run. This provides insight to administrators that was not previously available with the CLI being responsible for enforcing and performing image signature verification. From 75e3c4de87614e057408045cac27698a479536eb Mon Sep 17 00:00:00 2001 From: Anne Henmi <41210220+ahh-docker@users.noreply.github.com> Date: Thu, 25 Oct 2018 13:19:03 -0600 Subject: [PATCH 19/21] Update content_trust.md --- engine/security/trust/content_trust.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/engine/security/trust/content_trust.md b/engine/security/trust/content_trust.md index c3d9db3e5e..5109ae3644 100644 --- a/engine/security/trust/content_trust.md +++ b/engine/security/trust/content_trust.md @@ -182,6 +182,11 @@ The signature verification feature is configured in the Docker daemon configurat `permissive`: Verification will be performed, but only failures will only be logged and remain unenforced. This configuration is intended for testing of changes related to content-trust.
`enforced`: DCT will be enforced and an image that cannot be verified successfully will not be pulled or run. | +***Note:*** The DCT configuration defined here is agnostic of any policy defined in +[UCP](https://docs.docker.com/v17.09/datacenter/ucp/2.0/guides/content-trust/#configure-ucp). +Images that can be deployed by the UCP trust policy but are disallowed by the Docker Engine +configuration will not successfully be deployed or run on that engine. + ### Enable and disable DCT per-shell or per-invocation Instead of enabling DCT through the system-wide configuration, DCT can be enabled or disabled From 5fc2b2976821147063694766ac50d80c7f1eb401 Mon Sep 17 00:00:00 2001 From: Anne Henmi <41210220+ahh-docker@users.noreply.github.com> Date: Thu, 25 Oct 2018 15:23:30 -0600 Subject: [PATCH 20/21] Update security.md Incorporated @ddeyo's fixes --- engine/security/security.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/engine/security/security.md b/engine/security/security.md index cfe0655f4d..f4a761f6e2 100644 --- a/engine/security/security.md +++ b/engine/security/security.md @@ -201,14 +201,15 @@ those explicitly required for their processes. ## Docker Content Trust Signature Verification -The Docker Content Trust signature verification feature is built directly -into the `dockerd` binary. The Docker Engine can be configured to only run -signed images. This is configured in the Dockerd configuration file. +The Docker Engine can be configured to only run signed images. The Docker Content +Trust signature verification feature is built directly into the `dockerd` binary. +This is configured in the Dockerd configuration file. + To enable this feature, trustpinning can be configured in `daemon.json`, whereby only repositories signed with a user-specified root key can be pulled and run. -This provides insight to administrators that was not previously available with -the CLI being responsible for enforcing and performing image signature verification. +This feature provides more insight to administrators than previously available with +the CLI for enforcing and performing image signature verification. For more information on configuring Docker Content Trust Signature Verificiation, go to (Content trust in Docker)[engine/security/trust/content_trust]. From 3a5538dd99746a8b2b6391d53dce7ce72d3f4cea Mon Sep 17 00:00:00 2001 From: Anne Henmi <41210220+ahh-docker@users.noreply.github.com> Date: Thu, 25 Oct 2018 15:28:19 -0600 Subject: [PATCH 21/21] Update content_trust.md Incorporated @ddeyo's feedback --- engine/security/trust/content_trust.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/engine/security/trust/content_trust.md b/engine/security/trust/content_trust.md index 5109ae3644..a68fe3883f 100644 --- a/engine/security/trust/content_trust.md +++ b/engine/security/trust/content_trust.md @@ -20,14 +20,14 @@ Docker registries. These signatures allow client-side verification of the integrity and publisher of specific image tags. Once DCT is enabled, image publishers can sign their images. Image consumers -can ensure that the images they use are signed. Publishers and consumers can be individuals -alone or in organizations. DCT supports users and automated processes +can ensure that the images they use are signed. Publishers and consumers can +either be individuals or organizations. DCT supports users and automated processes such as builds. -When you enable DCT, signing occurs on the client after push and -verification happens on the client after pull if you use Docker CE. If you use -Docker EE with UCP, and you have configured UCP to require images to be signed -before deploying, signing is verified by UCP. +When you enable DCT, signing occurs on the client after push and verification +happens on the client after pull if you use Docker CE. If you use UCP, and you +have configured UCP to require images to be signed before deploying, signing is +verified by UCP. ### Image tags and DCT @@ -135,7 +135,7 @@ these various trusted operations: ### Enabling DCT in Docker Engine Configuration -Engine Signature Verification will prevent the following behaviors on an image: +Engine Signature Verification prevents the following behaviors on an image: * Running a container to build an image (the base image must be signed, or must be scratch) * Creating a container from an image that is not signed @@ -174,7 +174,7 @@ The signature verification feature is configured in the Docker daemon configurat | ***Stanza*** | ***Description*** | | ----------------------- |---------------| -| `trust-pinning:root-keys` | Root key IDs are canonical IDs that sign the root metadata of the image trust data. In Docker Certified Trust (DCT), the root keys are unique certificates tying the name of the image to the repo metadata.  The private key ID (the canonical key ID) corresponding to the certificate is not dependent on the image name. If an image’s name matches more than one glob, then the most specific (longest) one is chosen.| +| `trust-pinning:root-keys` | Root key IDs are canonical IDs that sign the root metadata of the image trust data. In Docker Certified Trust (DCT), the root keys are unique certificates tying the name of the image to the repo metadata.  The private key ID (the canonical key ID) corresponding to the certificate does not depend on the image name. If an image’s name matches more than one glob, then the most specific (longest) one is chosen.| |`trust-pinning:library-images` | This option pins the official libraries (`docker.io/library/*`) to the hard-coded Docker official images root key. DCT trusts the official images by default. This is in addition to whatever images are specified by `trust-pinning:root-keys`. If `trustpinning:root-keys` specifies a key mapping for `docker.io/library/*`, those keys will be preferred for trust pinning. Otherwise, if a more general `docker.io/*` or `*` are specified, the official images key will be preferred.| | `allow-expired-trust-cache` | Specifies whether cached locally expired metadata validates images if an external server is unreachable or does not have image trust metadata. This is necessary for machines which may be often offline, as may be the case for edge. This does not provide mitigations against freeze attacks, which is a necessary to provide availability in low-connectivity environments. | | `mode` | Specifies whether DCT is enabled and enforced. Valid modes are: