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