docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Edit signing images () 

* Edit signing images

* Incorporate feedback

* Final edits

- Change example Security member name
This commit is contained in:
Maria Bermudez 2019-06-04 21:40:21 -07:00 committed by Dawn W Docker
parent 6759a89704
commit 435f7d560b
1 changed files with 68 additions and 73 deletions
ee/dtr/user/manage-images/sign-images
index.md

141
ee/dtr/user/manage-images/sign-images/index.md
View File

@ -7,21 +7,21 @@ redirect_from:
- /ee/dtr/user/manage-images/sign-images/manage-trusted-repositories/ - /ee/dtr/user/manage-images/sign-images/manage-trusted-repositories/
--- ---
2 Key components of the Docker Trusted Registry are the Notary Server and Notary Two key components of the Docker Trusted Registry are the Notary Server and the Notary
Signer. These 2 containers give us the required components to use Docker Content Signer. These two containers provide the required components for using Docker Content
Trust right out of the box. [Docker Content Trust (DCT) out of the box. [Docker Content
Trust](/engine/security/trust/content_trust/) allows us to sign image tags, Trust](/engine/security/trust/content_trust/) allows you to sign image tags,
therefore whoever pulls the image can validate that they are getting the image therefore giving consumers a way to verify the integrity of your image.
you create, or a forged one.
As part of Docker Trusted Registry both the Notary server and the Registry As part of DTR, both the Notary and the Registry
server are accessed through a front end Proxy, with both components sharing the servers are accessed through a front-end proxy, with both components sharing the
UCP's RBAC Engine. Therefore no additional configuration of the Docker Client UCP's RBAC (Role-based Access Control) Engine. Therefore, you do not need additional Docker client
is required to use trust. configuration in order to use DCT.
Docker Content Trust is integrated into the Docker CLI, allowing you to DCT is integrated with the Docker CLI, and allows you to:
configure repositories, add signers and sign images all through the `$ docker - Configure repositories
trust` command. - Add signers, and
- Sign images using the `docker trust` command
![image without signature](../../../images/sign-an-image-1.svg) ![image without signature](../../../images/sign-an-image-1.svg)
@ -29,31 +29,29 @@ trust` command.
UCP has a feature which will prevent [untrusted UCP has a feature which will prevent [untrusted
images](/ee/ucp/admin/configure/run-only-the-images-you-trust/) from being images](/ee/ucp/admin/configure/run-only-the-images-you-trust/) from being
deployed on the cluster. To use this feature, we first need to upload and sign deployed on the cluster. To use the feature, you need to sign and push images to your DTR.
images into DTR. To tie the signed images back to UCP, we will actually sign the To tie the signed images back to UCP, you need to sign the
images with private keys of UCP users. Inside of a UCP Client bundle the images with the private keys of the UCP users. From a UCP client bundle, use
`key.pem` can be used a User's private key, with the `cert.pem` being a public `key.pem` as your private key, and `cert.pem` as your public key
key within a x509 certificate. on an `x509` certificate.
To sign images in a way that UCP trusts them, you need to: To sign images in a way that UCP can trust, you need to:
1. Download a Client Bundle for a User you want to use to sign the images. 1. Download a client bundle for the user account you want to use for signing the images.
2. Load the private key of the User into your workstations trust store. 2. Add the user's private key to your machine's trust store.
3. Initialize trust metadata for the repository. 3. Initialize trust metadata for the repository.
4. Delegate signing for that repository to the UCP User. 4. Delegate signing for that repository to the UCP user.
5. Sign the Image. 5. Sign the image.
In this example we're going to pull a nginx image from the Docker Hub, re-tag it The following example shows the `nginx` image getting pulled from Docker Hub, tagged
as `dtr.example.com/dev/nginx:1`, push the image to DTR and sign it in a way as `dtr.example.com/dev/nginx:1`, pushed to DTR, and signed in a way
that is trusted by UCP. If you manage multiple repositories, you'll have to do that is trusted by UCP.
the same procedure for each repository.
### Import a UCP User's Private Key ### Import a UCP user's private key
Once you have download and extracted a UCP User's client bundle into your local After downloading and extracting a UCP client bundle into your local
directory, you need to load the Private key into the local Docker trust store directory, you need to load the private key into the local Docker trust store
`(~/.docker/trust)`. The name used here is purely metadata to help keep track of `(~/.docker/trust)`. To illustrate the process, we will use `jeff` as an example user.
which keys you have imported.
```bash ```bash
$ docker trust key load --name jeff key.pem $ docker trust key load --name jeff key.pem
@ -63,16 +61,16 @@ Repeat passphrase for new jeff key with ID a453196:
Successfully imported key from key.pem Successfully imported key from key.pem
``` ```
### Initialize the trust metadata and add the Public Key ### Initialize the trust metadata and add the user's public certificate
Next, we need to initiate trust metadata for a DTR repository. If you have not Next,initiate trust metadata for a DTR repository. If you have not
done so already, navigate to the **DTR web UI**, and create a repository for already done so, navigate to the **DTR web UI**, and create a repository for
your image. In this example we've created the `prod/nginx` repository. your image. This example uses the `nginx` repository in the `prod` namespace.
As part of initiating the repository, we will add the public key of the UCP User As part of initiating the repository, the public key of the UCP user needs to be added
as a signer. You will be asked for a number of passphrases to protect the keys. to the Notary server as a signer for the repository. You will be asked for a number of
Make a note of these passphrases, and see [Managing Delegations in a Notary Server](/engine/security/trust/trust_delegation/#managing-delegations-in-a-notary-server) passphrases to protect the keys.Make a note of these passphrases, and
to learn more about managing keys. see [Managing Delegations in a Notary Server](/engine/security/trust/trust_delegation/#managing-delegations-in-a-notary-server) to learn more about managing keys.
```bash ```bash
@ -86,7 +84,7 @@ Successfully initialized "dtr.example.com/prod/nginx"
Successfully added signer: jeff to dtr.example.com/prod/nginx Successfully added signer: jeff to dtr.example.com/prod/nginx
``` ```
We can inspect the trust metadata of the repository to make sure the User has Inspect the trust metadata of the repository to make sure the user has
been added correctly. been added correctly.
```bash ```bash
@ -105,11 +103,10 @@ Administrative keys for dtr.example.com/prod/nginx
Root Key: b74854cb27cc25220ede4b08028967d1c6e297a759a6939dfef1ea72fbdd7b9a Root Key: b74854cb27cc25220ede4b08028967d1c6e297a759a6939dfef1ea72fbdd7b9a
``` ```
### Sign the Image ### Sign the image
Finally, we will sign an image tag. These steps download the Image from the Finally, user `jeff` can sign an image tag. The following steps include downloading the image from Hub, tagging the image for Jeff's DTR repository, pushing the image to Jeff's DTR, as
Docker Hub, retag the Image to the DTR repository, push the image up to DTR, as well as signing the tag with Jeff's keys.
well as signing the tag with the UCP User's keys.
```bash ```bash
$ docker pull nginx:latest $ docker pull nginx:latest
@ -128,7 +125,7 @@ Enter passphrase for jeff key with ID 927f303:
Successfully signed dtr.example.com/prod/nginx:1 Successfully signed dtr.example.com/prod/nginx:1
``` ```
We can inspect the trust metadata again to make sure the image tag has been Inspect the trust metadata again to make sure the image tag has been
signed successfully. signed successfully.
```bash ```bash
@ -150,49 +147,48 @@ Administrative keys for dtr.example.com/prod/nginx:1
Root Key: b74854cb27cc25220ede4b08028967d1c6e297a759a6939dfef1ea72fbdd7b9a Root Key: b74854cb27cc25220ede4b08028967d1c6e297a759a6939dfef1ea72fbdd7b9a
``` ```
Or we can have a look at the signed image from within the **DTR UI**. Alternatively, you can review the signed image from the DTR web UI.
![DTR](../../../images/sign-an-image-3.png){: .with-border} ![DTR](../../../images/sign-an-image-3.png){: .with-border}
### Adding Additional Delegations ### Add delegations
If you wanted to sign this image with multiple UCP Users, maybe if you had a use You have the option to sign an image using multiple UCP users' keys. For example, an image
case where an image needed to be signed by a member of the `Security` team and a needs to be signed by a member of the `Security` team and a
member of the `Developers` team. Then you can add multiple signers to a member of the `Developers` team. Let's assume `jeff` is a member of the Developers team.
repository. In this case, we only need to add a member of the Security team.
To do so, first load a private key from a UCP User of the Security Team's in to To do so, first add the private key of the Security team member to
the local Docker Trust Store. the local Docker trust store.
```bash ```bash
$ docker trust key load --name security key.pem $ docker trust key load --name ian key.pem
Loading key from "key.pem"... Loading key from "key.pem"...
Enter passphrase for new security key with ID 5ac7d9a: Enter passphrase for new ian key with ID 5ac7d9a:
Repeat passphrase for new security key with ID 5ac7d9a: Repeat passphrase for new ian key with ID 5ac7d9a:
Successfully imported key from key.pem Successfully imported key from key.pem
``` ```
Upload the Public Key to the Notary Server and Sign the Image. You will be asked Upload the user's public key to the Notary Server and sign the image. You will be asked
for both the Developers passphrase, as well as the Security Users passphrase to for `jeff`, the developer's passphrase, as well as the `ian` user's passphrase to
sign the tag. sign the tag.
```bash ```bash
$ docker trust signer add --key cert.pem security dtr.example.com/prod/nginx $ docker trust signer add --key cert.pem ian dtr.example.com/prod/nginx
Adding signer "security" to dtr.example.com/prod/nginx... Adding signer "ian" to dtr.example.com/prod/nginx...
Enter passphrase for repository key with ID e0d15a2: Enter passphrase for repository key with ID e0d15a2:
Successfully added signer: security to dtr.example.com/prod/nginx Successfully added signer: ian to dtr.example.com/prod/nginx
$ docker trust sign dtr.example.com/prod/nginx:1 $ docker trust sign dtr.example.com/prod/nginx:1
Signing and pushing trust metadata for dtr.example.com/prod/nginx:1 Signing and pushing trust metadata for dtr.example.com/prod/nginx:1
Existing signatures for tag 1 digest 5b49c8e2c890fbb0a35f6050ed3c5109c5bb47b9e774264f4f3aa85bb69e2033 from: Existing signatures for tag 1 digest 5b49c8e2c890fbb0a35f6050ed3c5109c5bb47b9e774264f4f3aa85bb69e2033 from:
jeff jeff
Enter passphrase for jeff key with ID 927f303: Enter passphrase for jeff key with ID 927f303:
Enter passphrase for security key with ID 5ac7d9a: Enter passphrase for ian key with ID 5ac7d9a:
Successfully signed dtr.example.com/prod/nginx:1 Successfully signed dtr.example.com/prod/nginx:1
``` ```
Finally, we can check the tag again to make sure it is now signed by 2 Finally, check the tag again to make sure it includes two signers.
signatures.
```bash ```bash
$ docker trust inspect --pretty dtr.example.com/prod/nginx:1 $ docker trust inspect --pretty dtr.example.com/prod/nginx:1
@ -200,13 +196,13 @@ $ docker trust inspect --pretty dtr.example.com/prod/nginx:1
Signatures for dtr.example.com/prod/nginx:1 Signatures for dtr.example.com/prod/nginx:1
SIGNED TAG DIGEST SIGNERS SIGNED TAG DIGEST SIGNERS
1 5b49c8e2c890fbb0a35f6050ed3c5109c5bb47b9e774264f4f3aa85bb69e2033 jeff, security 1 5b49c8e2c890fbb0a35f6050ed3c5109c5bb47b9e774264f4f3aa85bb69e2033 jeff, ian
List of signers and their keys for dtr.example.com/prod/nginx:1 List of signers and their keys for dtr.example.com/prod/nginx:1
SIGNER KEYS SIGNER KEYS
jeff 927f30366699 jeff 927f30366699
security 5ac7d9af7222 ian 5ac7d9af7222
Administrative keys for dtr.example.com/prod/nginx:1 Administrative keys for dtr.example.com/prod/nginx:1
@ -218,13 +214,12 @@ For more advanced use cases like this, see [Delegations for content trust](/engi
## Delete trust data ## Delete trust data
If an Administrator wants to delete a DTR repository that contains Trust If an administrator wants to delete a DTR repository that contains trust
metadata, they will be prompted to delete the trust metadata first before the metadata, they will be prompted to delete the trust metadata first before removing the repository.
repository can be removed.
To delete trust metadata we need to use the Notary CLI. For information on how To delete trust metadata, you need to use the Notary CLI. For information on how
to download and configure the Notary CLI head to download and configure the Notary CLI see
[here](/engine/security/trust/trust_delegation/#configuring-the-notary-client) [Configuring the Notary client](/engine/security/trust/trust_delegation/#configuring-the-notary-client)
```bash ```bash