Merge pull request #8426 from ollypom/contenttrustpatch

Updated Content Trust Docs

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 

engine/security/trust/trust_delegation.md

@@ -7,33 +7,31 @@ redirect_from:
 ---
 
 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 
+an image tag. A delegation will have a pair of private and public delegation keys. A delegation 
-private. A delegation could contain multiple pairs of keys, contributors, to 
+could contain multiple pairs of keys and contributors in order to a) allow multiple users 
-allow multiple users to be part of a delegation, and to support key rotation.  
+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
+initialize a repository, manage the repository keys, and add a collaborator's key to the 
-gets added with `docker trust signer add` we will add their key to the 
+`targets/releases` delegation via `docker trust signer add`. 
-`targets/releases` delegation automatically. 
 
 ## Configuring the Docker Client
 
-By default the `$ docker trust` commands are expecting the Notary server URL
+By default, the `$ docker trust` commands expect the notary server URL
-to be the same as the Docker Registry URL specified in the image tag. When 
+to be the same as the Docker Trusted Registry (DTR) URL specified in the image tag. This is because an 
-using the Docker Hub or Docker Trusted Registry this is the case as a internal 
+internal proxy redirects the request when you are using Docker Hub or DTR. However, for self-hosted environments 
-proxy redirects the request; however for self hosted environments or 3rd party 
+or 3rd party registries, you will need to specify an alternative URL for the notary server. 
-registries you will need to specify an alternative URL for the notary server. 
 This is done with:
 
 ```
 export DOCKER_CONTENT_TRUST_SERVER=https://<URL>:<PORT>
 ```
 
-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: 
 
 ```
@@ -47,15 +45,43 @@ WARN[0000] Error while downloading remote metadata, using cached timestamp - thi
 [...]
 ```
 
+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
+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 log in, 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 
 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:
 
 ```
 {
@@ -67,10 +93,9 @@ and ensure that it is available on your path
 }
 ```
 
-This configuration file will tell Notary where the local Docker Trust data is 
+The newly created configuration file contains information about the location of your local Docker trust data and the notary server URL.
-stored, as well as which Notary server to use by default.
 
-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)