From eb68c3d408c79edb4a8ea7e6efdf736c077eb7d4 Mon Sep 17 00:00:00 2001 From: ollypom Date: Fri, 8 Mar 2019 16:11:02 +0000 Subject: [PATCH 1/3] Added Docker Pull to the content trust verification process --- engine/security/trust/content_trust.md | 1 + 1 file changed, 1 insertion(+) diff --git a/engine/security/trust/content_trust.md b/engine/security/trust/content_trust.md index fd82810f1f..9766c6fa91 100644 --- a/engine/security/trust/content_trust.md +++ b/engine/security/trust/content_trust.md @@ -230,6 +230,7 @@ trusted sources, with repositories and tags signed with the commands [above](#si Engine Signature Verification prevents the following: * `$ docker container run` of an unsigned image. +* `$ docker pull` of an unsigned image. * `$ docker build` where the `FROM` image is not signed or is not scratch. DCT does not verify that a running container’s filesystem has not been altered From 9a00acab84d6bcfe8b87e27e165df25bc43920eb Mon Sep 17 00:00:00 2001 From: ollypom Date: Fri, 8 Mar 2019 16:23:06 +0000 Subject: [PATCH 2/3] Using Docker Trust with a Notary Server with Auth --- engine/security/trust/trust_delegation.md | 29 +++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/engine/security/trust/trust_delegation.md b/engine/security/trust/trust_delegation.md index 2aa6e46973..23479081f2 100644 --- a/engine/security/trust/trust_delegation.md +++ b/engine/security/trust/trust_delegation.md @@ -45,6 +45,35 @@ WARN[0000] Error while downloading remote metadata, using cached timestamp - thi [...] ``` +If you have enabled Authentication for your Notary Server, or are using Docker +Trusted Registry, you will need to login before you can push data to the Notary +Server. + +``` +$ docker login dtr.example.com/user/repo +Username: admin +Password: + +Login Succeeded + +$ docker trust signer add --key cert.pem jeff dtr.example.com/user/repo +Adding signer "jeff" to dtr.example.com/user/repo... +Initializing signed repository for dtr.example.com/user/repo... +Successfully initialized "dtr.example.com/user/repo" +Successfully added signer: jeff to dtr.example.com/user/repo +``` + +If you do not login, you will see: + +```bash +$ docker trust signer add --key cert.pem jeff dtr.example.com/user/repo +Adding signer "jeff" to dtr.example.com/user/repo... +Initializing signed repository for dtr.example.com/user/repo... +you are not authorized to perform this operation: server returned 401. + +Failed to add signer to: dtr.example.com/user/repo +``` + ## Configuring the Notary Client Some of the more advanced features of DCT require the Notary CLI. To install and From f9c29e21255359046c3c11e6d31d15c60c2e3670 Mon Sep 17 00:00:00 2001 From: Maria Bermudez Date: Fri, 8 Mar 2019 15:49:29 -0800 Subject: [PATCH 3/3] Editorial review --- engine/security/trust/trust_delegation.md | 38 ++++++++++------------- 1 file changed, 17 insertions(+), 21 deletions(-) diff --git a/engine/security/trust/trust_delegation.md b/engine/security/trust/trust_delegation.md index 23479081f2..9b728e0d31 100644 --- a/engine/security/trust/trust_delegation.md +++ b/engine/security/trust/trust_delegation.md @@ -5,33 +5,31 @@ title: Delegations for content trust --- Delegations in Docker Content Trust (DCT) allow you to control who can and cannot sign -an image tag. A delegation will have a pair of delegation keys, public and -private. A delegation could contain multiple pairs of keys, contributors, to -allow multiple users to be part of a delegation, and to support key rotation. +an image tag. A delegation will have a pair of private and public delegation keys. A delegation +could contain multiple pairs of keys and contributors in order to a) allow multiple users +to be part of a delegation, and b) to support key rotation. The most important delegation within Docker Content Trust is `targets/releases`. This is seen as the canonical source of a trusted image tag, and without a contributor's key being under this delegation, they will be unable to sign a tag. Fortunately when using the `$ docker trust` commands, we will automatically -initialise a repository, manage the repository keys, and when a collaborator -gets added with `docker trust signer add` we will add their key to the -`targets/releases` delegation automatically. +initialize a repository, manage the repository keys, and add a collaborator's key to the +`targets/releases` delegation via `docker trust signer add`. ## Configuring the Docker Client -By default the `$ docker trust` commands are expecting the Notary server URL -to be the same as the Docker Registry URL specified in the image tag. When -using the Docker Hub or Docker Trusted Registry this is the case as a internal -proxy redirects the request; however for self hosted environments or 3rd party -registries you will need to specify an alternative URL for the notary server. +By default, the `$ docker trust` commands expect the notary server URL +to be the same as the Docker Trusted Registry (DTR) URL specified in the image tag. This is because an +internal proxy redirects the request when you are using Docker Hub or DTR. However, for self-hosted environments +or 3rd party registries, you will need to specify an alternative URL for the notary server. This is done with: ``` export DOCKER_CONTENT_TRUST_SERVER=https://: ``` -If you do not export this variable in self-hosted environments you may see +If you do not export this variable in self-hosted environments, you may see errors such as: ``` @@ -45,9 +43,8 @@ WARN[0000] Error while downloading remote metadata, using cached timestamp - thi [...] ``` -If you have enabled Authentication for your Notary Server, or are using Docker -Trusted Registry, you will need to login before you can push data to the Notary -Server. +If you have enabled authentication for your notary server, or are using DTR, you will need to log in +before you can push data to the notary server. ``` $ docker login dtr.example.com/user/repo @@ -63,7 +60,7 @@ Successfully initialized "dtr.example.com/user/repo" Successfully added signer: jeff to dtr.example.com/user/repo ``` -If you do not login, you will see: +If you do not log in, you will see: ```bash $ docker trust signer add --key cert.pem jeff dtr.example.com/user/repo @@ -80,9 +77,9 @@ Some of the more advanced features of DCT require the Notary CLI. To install and configure the Notary CLI: 1) Download the [client](https://github.com/theupdateframework/notary/releases) -and ensure that it is available on your path +and ensure that it is available on your path. -2) Create a configuration file at ~/.notary/config.json with the following content: +2) Create a configuration file at `~/.notary/config.json` with the following content: ``` { @@ -94,10 +91,9 @@ and ensure that it is available on your path } ``` -This configuration file will tell Notary where the local Docker Trust data is -stored, as well as which Notary server to use by default. +The newly created configuration file contains information about the location of your local Docker trust data and the notary server URL. -For more detailed information about how to use Notary outside of the +For more detailed information about how to use notary outside of the Docker Content Trust use cases, refer to the Notary CLI documentation [here](https://github.com/theupdateframework/notary/blob/master/docs/command_reference.md)