1. docker
  2. Commit 88d73ebff43ef6031f169e8333f2d67e4f4f9d93
Browse code

Include documentation on how to add the targets/releases delegation to a repo

Signed-off-by: cyli <cyli@twistedmatrix.com>

cyli authored on 2016/03/19 08:11:37
Showing 5 changed files
docs/security/trust/content_trust.md
History View file @ 88d73eb
... ... 
@@ -108,19 +108,13 @@ $ docker pull someimage@sha256:d149ab53f8718e987c3a3024bb8aa0e2caadf6c0328f1d9d8
108 108 
 ```
109 109
110 110 
 Trust for an image tag is managed through the use of signing keys. A key set is
111 
-created when an operation using content trust is first invoked. Docker's content
112 
-trust makes use of four different keys:
111 
+created when an operation using content trust is first invoked. A key set consists
112 
+of the following classes of keys:
113 113
114 
-| Key                 | Description                                                                                                                                                                                                                                                                                                                                                                         |
115 
-|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
116 
-| root key         | Root of content trust for a image tag. When content trust is enabled, you create the root key once. |
117 
-| target and snapshot | These two keys are known together as the "repository" key. When content trust is enabled, you create this key when you add a new image repository. If you have the root key, you can export the repository key and allow other publishers to sign the image tags.    |
118 
-| timestamp           | This key applies to a repository. It allows Docker repositories to have freshness security guarantees without requiring periodic content refreshes on the client's side.                                                                                                              |
119 
-
120 
-With the exception of the timestamp, all the keys are generated and stored locally
121 
-client-side. The timestamp is safely generated and stored in a signing server that
122 
-is deployed alongside the Docker registry. All keys are generated in a backend
123 
-service that isn't directly exposed to the internet and are encrypted at rest.
114 
+- an offline key that is the root of content trust for a image tag
115 
+- repository or tagging keys that sign tags
116 
+- server-managed keys such as the timestamp key, which provides freshness
117 
+	security guarantees for your repository
124 118
125 119 
 The following image depicts the various signing keys and their relationships:
126 120
... ... 
@@ -133,9 +127,9 @@ The following image depicts the various signing keys and their relationships:
133 133 
 >tag from this repository prior to the loss.
134 134
135 135 
 You should backup the root key somewhere safe. Given that it is only required
136 
-to create new repositories, it is a good idea to store it offline. Make sure you
137 
-read [Manage keys for content trust](trust_key_mng.md) information
138 
-for details on securing, and backing up your keys.
136 
+to create new repositories, it is a good idea to store it offline.
137 
+For details on securing, and backing up your keys, make sure you
138 
+read how to [manage keys for content trust](trust_key_mng.md).
139 139
140 140 
 ## Survey of typical content trust operations
141 141
... ... 
@@ -302,4 +296,5 @@ $  docker push --disable-content-trust docker/trusttest:untrusted
302 302
303 303 
 * [Manage keys for content trust](trust_key_mng.md)
304 304 
 * [Automation with content trust](trust_automation.md)
305 
+* [Delegations for content trust](trust_delegation.md)
305 306 
 * [Play in a content trust sandbox](trust_sandbox.md)
docs/security/trust/index.md
History View file @ 88d73eb
... ... 
@@ -17,4 +17,5 @@ The following topics are available:
17 17 
 * [Content trust in Docker](content_trust.md)
18 18 
 * [Manage keys for content trust](trust_key_mng.md)
19 19 
 * [Automation with content trust](trust_automation.md)
20 
+* [Delegations for content trust](trust_delegation.md)
20 21 
 * [Play in a content trust sandbox](trust_sandbox.md)
docs/security/trust/trust_automation.md
History View file @ 88d73eb
... ... 
@@ -73,7 +73,8 @@ unable to process Dockerfile: No trust data for notrust
73 73
74 74 
 ## Related information
75 75
76 
-* [Content trust in Docker](content_trust.md)
76 
+* [Content trust in Docker](content_trust.md)
77 77 
 * [Manage keys for content trust](trust_key_mng.md)
78 
+* [Delegations for content trust](trust_delegation.md)
78 79 
 * [Play in a content trust sandbox](trust_sandbox.md)
79 80
docs/security/trust/trust_delegation.md
History View file @ 88d73eb
80 81 
new file mode 100644
... ... 
@@ -0,0 +1,226 @@
0 
+<!--[metadata]>
1 
+title = "Delegations for content trust"
2 
+description = "Delegations for content trust"
3 
+keywords = ["trust, security, delegations, keys, repository"]
4 
+[menu.main]
5 
+parent= "smn_content_trust"
6 
+<![end-metadata]-->
7 
+
8 
+# Delegations for content trust
9 
+
10 
+Docker Engine supports the usage of the `targets/releases` delegation as the
11 
+canonical source of a trusted image tag.
12 
+
13 
+Using this delegation allows you to collaborate with other publishers without
14 
+sharing your repository key (a combination of your targets and snapshot keys -
15 
+please see "[Manage keys for content trust](trust_key_mng.md)" for more information).
16 
+A collaborator can keep their own delegation key private.
17 
+
18 
+The `targest/releases` delegation is currently an optional feature - in order
19 
+to set up delegations, you must use the Notary CLI:
20 
+
21 
+1. [Download the client](https://github.com/docker/notary/releases) and ensure that it is
22 
+available on your path
23 
+
24 
+2. Create a configuration file at `~/.notary/config.json` with the following content:
25 
+
26 
+	```
27 
+	{
28 
+	  "trust_dir" : "~/.docker/trust",
29 
+	  "remote_server": {
30 
+	    "url": "https://notary.docker.io"
31 
+	  }
32 
+	}
33 
+	```
34 
+
35 
+	This tells Notary where the Docker Content Trust data is stored, and to use the
36 
+	Notary server used for images in Docker Hub.
37 
+
38 
+For more detailed information about how to use Notary outside of the default
39 
+Docker Content Trust use cases, please refer to the
40 
+[the Notary CLI documentation](https://docs.docker.com/notary/getting_started/).
41 
+
42 
+Note that when publishing and listing delegation changes using the Notary client,
43 
+your Docker Hub credentials are required.
44 
+
45 
+## Generating delegation keys
46 
+
47 
+Your collaborator needs to generate a private key (either RSA or ECDSA)
48 
+and give you the public key so that you can add it to the `targets/releases`
49 
+delegation.
50 
+
51 
+The easiest way to for them to generate these keys is with OpenSSL.
52 
+Here is an example of how to generate a 2048-bit RSA portion key (all RSA keys
53 
+must be at least 2048 bits):
54 
+
55 
+```
56 
+$ opensl genrsa -out delegation.key 2048
57 
+Generating RSA private key, 2048 bit long modulus
58 
+....................................................+++
59 
+............+++
60 
+e is 65537 (0x10001)
61 
+
62 
+```
63 
+
64 
+They should keep `delegation.key` private - this is what they will use to sign
65 
+tags.
66 
+
67 
+Then they need to generate a x509 certificate containing the public key, which is
68 
+what they will give to you.  Here is the command to generate a CSR (certificate
69 
+signing request):
70 
+
71 
+```
72 
+$ openssl req -new -sha256 -key delegation.key -out delegation.csr
73 
+```
74 
+
75 
+Then they can send it to whichever CA you trust to sign certificates, or they
76 
+can self-sign the certificate (in this example, creating a certificate that is
77 
+valid for 1 year):
78 
+
79 
+```
80 
+$ openssl x509 -req -days 365 -in delegation.csr -signkey delegation.key -out delegation.crt
81 
+```
82 
+
83 
+Then they need to give you `delegation.crt`, whether it is self-signed or signed
84 
+by a CA.
85 
+
86 
+## Adding a delegation key to an existing repository
87 
+
88 
+If your repository was created using a version of Docker Engine prior to 1.11,
89 
+then before adding any delegations, you should rotate the snapshot key to the server
90 
+so that collaborators will not require your snapshot key to sign and publish tags:
91 
+
92 
+```
93 
+$ notary key rotate docker.io/<username>/<imagename> snapshot -r
94 
+```
95 
+
96 
+This tells Notary to rotate a key for your particular image repository - note that
97 
+you must include the `docker.io/` prefix.  `snapshot -r` specifies that you want
98 
+to rotate the snapshot key specifically, and you want the server to manage it (`-r`
99 
+stands for "remote").
100 
+
101 
+When adding a delegation, your must acquire
102 
+[the PEM-encoded x509 certificate with the public key](#generating-delegation-keys)
103 
+of the collaborator you wish to delegate to.
104 
+
105 
+Assuming you have the certificate `delegation.crt`, you can add a delegation
106 
+for this user and then publish the delegation change:
107 
+
108 
+```
109 
+$ notary delegation add docker.io/<username>/<imagename> targets/releases delegation.crt --all-paths
110 
+$ notary publish docker.io/<username>/<imagename>
111 
+```
112 
+
113 
+The preceding example illustrates a request to add the delegation
114 
+`targets/releases` to the image repository, if it doesn't exist.  Be sure to use
115 
+`targets/releases` - Notary supports multiple delegation roles, so if you mistype
116 
+the delegation name, the Notary CLI will not error.  However, Docker Engine
117 
+supports reading only from `targets/releases`.
118 
+
119 
+It also adds the collaborator's public key to the delegation, enabling them to sign
120 
+the `targets/releases` delegation so long as they have the private key corresponding
121 
+to this public key.  The `--all-paths` flags tells Notary not to restrict the tag
122 
+names that can be signed into `targets/releases`, which we highly recommend for
123 
+`targets/releases`.
124 
+
125 
+Publishing the changes tells the server about the changes to the `targets/releases`
126 
+delegation.
127 
+
128 
+After publishing, view the delegation information to ensure that you correctly added
129 
+the keys to `targets/releases`:
130 
+
131 
+```
132 
+$ notary delegation list docker.io/<username>/<imagename>
133 
+
134 
+      ROLE               PATHS                                   KEY IDS                                THRESHOLD
135 
+---------------------------------------------------------------------------------------------------------------
136 
+  targets/releases   "" <all paths>  729c7094a8210fd1e780e7b17b7bb55c9a28a48b871b07f65d97baf93898523a   1
137 
+```
138 
+
139 
+You can see the `targets/releases` with its paths and the key ID you just added.
140 
+
141 
+Notary currently does not map collaborators names to keys, so we recommend
142 
+that you add and list delegation keys one at a time, and keep a mapping of the key
143 
+IDs to collaborators yourself should you need to remove a collaborator.
144 
+
145 
+## Removing a delegation key from an existing repository
146 
+
147 
+To revoke a collaborator's permission to sign tags for your image repository, you must
148 
+know the IDs of their keys, because you need to remove their keys from the
149 
+`targets/releases` delegation.
150 
+
151 
+```
152 
+$ notary delegation remove docker.io/<username>/<imagename> targets/releases 729c7094a8210fd1e780e7b17b7bb55c9a28a48b871b07f65d97baf93898523a
153 
+
154 
+Removal of delegation role targets/releases with keys [729c7094a8210fd1e780e7b17b7bb55c9a28a48b871b07f65d97baf93898523a], to repository "docker.io/<username>/<imagename>" staged for next publish.
155 
+```
156 
+
157 
+The revocation will take effect as soon as you publish:
158 
+
159 
+```
160 
+$ notary publish docker.io/<username>/<imagename>
161 
+```
162 
+
163 
+Note that by removing all the keys from the `targets/releases` delegation, the
164 
+delegation (and any tags that are signed into it) is removed.  That means that
165 
+these tags will all be deleted, and you may end up with older, legacy tags that
166 
+were signed directly by the targets key.
167 
+
168 
+## Removing the `targets/releases` delegation entirely from a repository
169 
+
170 
+If you've decided that delegations aren't for you, you can delete the
171 
+`targets/releases` delegation entirely. This also removes all the tags that
172 
+are currently in `targets/releases`, however, and you may end up with older,
173 
+legacy tags that were signed directly by the targets key.
174 
+
175 
+To delete the `targets/releases` delegation:
176 
+
177 
+```
178 
+$ notary delegation remove docker.io/<username>/<imagename> targets/releases
179 
+
180 
+Are you sure you want to remove all data for this delegation? (yes/no)
181 
+yes
182 
+
183 
+Forced removal (including all keys and paths) of delegation role targets/releases to repository "docker.io/<username>/<imagename>" staged for next publish.
184 
+
185 
+$ notary publish docker.io/<username>/<imagename>
186 
+```
187 
+
188 
+## Pushing trusted data as a collaborator
189 
+
190 
+As a collaborator with a private key that has been added to a repository's
191 
+`targets/releases` delegation, you need to import the private key that you
192 
+generated into Content Trust.
193 
+
194 
+To do so, you can run:
195 
+
196 
+```
197 
+$ notary key import delegation.key --role user
198 
+```
199 
+
200 
+where `delegation.key` is the file containing your PEM-encoded private key.
201 
+
202 
+After you have done so, running `docker push` on any repository that
203 
+includes your key in the `targets/releases` delegation will automatically sign
204 
+tags using this imported key.
205 
+
206 
+## `docker push` behavior
207 
+
208 
+When running `docker push` with Docker Content Trust, Docker Engine
209 
+will attempt to sign and push with the `targets/releases` delegation if it exists.
210 
+If it does not, the targets key will be used to sign the tag, if the key is available.
211 
+
212 
+## `docker pull` and `docker build` behavior
213 
+
214 
+When running `docker pull` or `docker build` with Docker Content Trust, Docker
215 
+Engine will pull tags only signed by the `targets/releases` delegation role or
216 
+the legacy tags that were signed directly with the `targets` key.
217 
+
218 
+## Related information
219 
+
220 
+* [Content trust in Docker](content_trust.md)
221 
+* [Manage keys for content trust](trust_key_mng.md)
222 
+* [Automation with content trust](trust_automation.md)
223 
+* [Play in a content trust sandbox](trust_sandbox.md)
docs/security/trust/trust_key_mng.md
History View file @ 88d73eb
... ... 
@@ -11,18 +11,34 @@ parent= "smn_content_trust"
11 11 
 # Manage keys for content trust
12 12
13 13 
 Trust for an image tag is managed through the use of keys. Docker's content
14 
-trust makes use four different keys:
14 
+trust makes use of five different types of keys:
15 15
16 16 
 | Key                 | Description                                                                                                                                                                                                                                                                                                                                                                         |
17 17 
 |---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
18 
-| root key         | Root of content trust for a image tag. When content trust is enabled, you create the root key once. |
19 
-| target and snapshot | These two keys are known together as the "repository" key. When content trust is enabled, you create this key when you add a new image repository. If you have the root key, you can export the repository key and allow other publishers to sign the image tags.    |
20 
-| timestamp           | This key applies to a repository. It allows Docker repositories to have freshness security guarantees without requiring periodic content refreshes on the client's side.                                                                                                              |
18 
+| root key         | Root of content trust for a image tag. When content trust is enabled, you create the root key once. Also known as the offline key, because it should be kept offline. |
19 
+| targets          | This key allows you to sign image tags, to manage delegations including delegated keys or permitted delegation paths. Also known as the repository key, since this key determines what tags can be signed into an image repository. |
20 
+| snapshot         | This key signs the current collection of image tags, preventing mix and match attacks.
21 
+| timestamp        | This key allows Docker image repositories to have freshness security guarantees without requiring periodic content refreshes on the client's side. |
22 
+| delegation       | Delegation keys are optional tagging keys and allow you to delegate signing image tags to other publishers without having to share your targets key. |
21 23
22 
-With the exception of the timestamp, all the keys are generated and stored locally
23 
-client-side. The timestamp is safely generated and stored in a signing server that
24 
-is deployed alongside the Docker registry. All keys are generated in a backend
25 
-service that isn't directly exposed to the internet and are encrypted at rest.
24 
+When doing a `docker push` with Content Trust enabled for the first time, the
25 
+root, targets, snapshot, and timestamp keys are generated automatically for
26 
+the image repository:
27 
+
28 
+- The root and targets key are generated and stored locally client-side.
29 
+
30 
+- The timestamp and snapshot keys are safely generated and stored in a signing server
31 
+	that is deployed alongside the Docker registry. These keys are generated in a backend
32 
+	service that isn't directly exposed to the internet and are encrypted at rest.
33 
+
34 
+Delegation keys are optional, and not generated as part of the normal `docker`
35 
+workflow.  They need to be
36 
+[manually generated and added to the repository](trust_delegation.md#generating-delegation-keys).
37 
+
38 
+Note: Prior to Docker Engine 1.11, the snapshot key was also generated and stored
39 
+locally client-side. [Use the Notary CLI to manage your snapshot key locally
40 
+again](https://docs.docker.com/notary/advanced_usage/#rotate-keys) for
41 
+repositories created with newer versions of Docker.
26 42
27 43 
 ## Choosing a passphrase
28 44
... ... 
@@ -68,6 +84,7 @@ the new key.
68 68
69 69 
 ## Related information
70 70
71 
-* [Content trust in Docker](content_trust.md)
71 
+* [Content trust in Docker](content_trust.md)
72 72 
 * [Automation with content trust](trust_automation.md)
73 
+* [Delegations for content trust](trust_delegation.md)
73 74 
 * [Play in a content trust sandbox](trust_sandbox.md)