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

Added managing Delegation Documentation

This commit is contained in:
Olly P 2019-01-20 13:13:30 +00:00
parent ae12369696
commit 72a288caa2
3 changed files with 428 additions and 199 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

124
engine/security/trust/content_trust.md
View File

@ -7,27 +7,22 @@ title: Content trust in Docker
When transferring data among networked systems, *trust* is a central concern. In
particular, when communicating over an untrusted medium such as the internet, it
is critical to ensure the integrity and the publisher of all the data a system
operates on. You use Docker Engine to push and pull images (data) to a public
or private registry. Content trust gives you the ability to verify both the
integrity and the publisher of all the data received from a registry over any
channel.
operates on. You use the Docker Engine to push and pull images (data) to a
public or private registry. Content trust gives you the ability to verify both
the integrity and the publisher of all the data received from a registry over
any channel.
## About trust in Docker
Docker Content Trust (DCT) allows operations with a remote Docker registry to
enforce client-side signing and runtime verification of image tags. DCT provides
the ability to use digital signatures for data sent to and received from remote
Docker registries. These signatures allow client-side or runtime verification of
the integrity and publisher of specific image tags.
Docker Content Trust (DCT) provides the ability to use digital signatures for
data sent to and received from remote Docker registries. These signatures allow
client-side or runtime verification of the integrity and publisher of specific
image tags.
Through DCT image publishers can sign their images. Image consumers can ensure
that the images they use are signed. Publishers and consumers can either be
individuals or organizations. DCT supports individual users / teams as well as
automated processes such as [builds and pipelines](trust_automation.d).
When you use DCT, signing occurs on the client through the `$ docker push` or
`$ docker trust sign` commands and verification can happen through the client,
the engine, or through Docker Enterprise's Universal Control Plane.
Through DCT image publishers can sign their images and image consumers can
ensure that the images they use are signed. Publishers could be be individuals
or organizations manually signing their content or automated software supply
chains signing content as part of their release process.
### Image tags and DCT
@ -111,29 +106,29 @@ Within the Docker CLI we can sign and push a container image with the
`$ docker trust` command syntax. This is built on top of the Notary feature
set, more information on Notary can be found [here](/notary/getting_started/).
A pre-requisite for signing an image is a Docker Registry with a Notary server
A prerequisite for signing an image is a Docker Registry with a Notary server
attached (Such as the Docker Hub or Docker Trusted Registry). Instructions for
standing up a self hosted environment can be found [here](/engine/security/trust/deploying_notary/).
Secondly to sign a Docker Image you will need a delegation's key pair. These
Secondly to sign a Docker Image you will need a delegation key pair. These keys
can either be generated locally using `$ docker trust key generate`, generated
by a certificate authority as discussed
[here](/engine/security/trust/trust_delegation/#generating-delegation-keys).
Alternatively if you are using Docker Enterprise's Universal Control Plane, a
user's [Client Bundle](ee/ucp/user-access/cli/#download-client-certificates)
provides adequate keys for a delegation. The `cert.pem` being the public
delegation key, the `key.pem` as the private delegation key.
by a certificate authority, or alternatively if you are using Docker Enterprise's
Universal Control Plane, a user's Client Bundle provides adequate keys for a
delegation. Find more information on Delegation Keys
[here](trust_delegation/#creating-delegation-keys).
First we will add the delegation's private key to the local docker trust
First we will add the delegation private key to the local docker trust
repository. (By default this is stored in `~/.docker/trust/`). If you are
generating with the key with `$ docker trust key generate` is it automatically
added to the store. If you are importing a seperate key, such as one from
the Universal Control Plane you will need to use the `$ docker trust key load`
command.
generating delegation key's with `$ docker trust key generate`, the private key
is automatically added to the local trust store. If you are importing a seperate
key, such as one from the Universal Control Plane you will need to use the
`$ docker trust key load` command.
```
$ docker trust key generate jeff
Generating key for jeff...
Enter passphrase for new jeff key with ID 9deed25:
Repeat passphrase for new jeff key with ID 9deed25:
Successfully generated and loaded private key. Corresponding public key available: /home/ubuntu/Documents/mytrustdir/jeff.pub
```
@ -141,15 +136,19 @@ Or if you have an existing key:
```
$ docker trust key load key.pem --name jeff
Loading key from "delegation.key"...
Loading key from "key.pem"...
Enter passphrase for new jeff key with ID 8ae710e:
Repeat passphrase for new jeff key with ID 8ae710e:
Successfully imported key from delegation.key
Successfully imported key from key.pem
```
Next we will need to add the delegation's public key to the Notary server,
this specific to a particular image repository (In Notary known as a Global
Unique Name (GUN)).
Next we will need to add the delegation public key to the Notary server,
this is specific to a particular image repository, in Notary known as a Global
Unique Name (GUN). If this is the first time you are adding a delegation to that
repository, this command will also initiate the repository, using a local Notary
canonical root key. To understand more about initiating a repository, and the
role of delegations head to
[delegations for content trust](trust_delegation/#managing-delegations-in-a-notary-server)
```
$ docker trust signer add --key cert.pem jeff dtr.example.com/admin/demo
@ -158,7 +157,7 @@ Enter passphrase for new repository key with ID 10b5e94:
```
Finally we will use the delegation's private key to sign a particular tag and
Finally we will use the delegation private key to sign a particular tag and
push it up to the registry.
```
@ -173,10 +172,11 @@ Successfully signed dtr.example.com/admin/demo:1
```
Alternatively, once the key's have been imported an image can be pushed with the
`$ docker push` command, by enabled the DCT environmental variable.
`$ docker push` command, by exporting the DCT environmental variable.
```
$ export DOCKER_CONTENT_TRUST=1
$ docker push dtr.example.com/admin/demo:1
The push refers to repository [dtr.example.com/admin/demo:1]
7bff100f35cb: Pushed
@ -186,8 +186,8 @@ Enter passphrase for signer key with ID 8ae710e:
Successfully signed dtr.example.com/admin/demo:1
```
Remote trust data for a tag can be viewed by the `$ docker trust inspect`
command:
Remote trust data for a tag or a repository can be viewed by the
`$ docker trust inspect` command:
```
$ docker trust inspect --pretty dtr.example.com/admin/demo:1
@ -200,7 +200,7 @@ SIGNED TAG DIGEST
List of signers and their keys for dtr.example.com/admin/demo:1
SIGNER KEYS
myteam 8ae710e3ba82
jeff 8ae710e3ba82
Administrative keys for dtr.example.com/admin/demo:1
@ -220,18 +220,15 @@ Successfully deleted signature for dtr.example.com/admin/demo:1
## Runtime Enforcement with Docker Content Trust
> Note this only applies to Docker Enterprise Engine 18.09 or newer. This
> implementation is also seperate from the `only run signed images` feature of
> implementation is also separate from the `only run signed images` feature of
> [Universal Control Plane](/ee/ucp/admin/configure/run-only-the-images-you-trust/)
Docker Content Trust within the Docker Enterprise Engine prevents a user from
using container image from an unknown source, it will also prevent a user from
building a container image, from a base layer from an unknown source. Docker
provides signatures on its Official Docker Images, found on the [Docker
Hub](https://hub.docker.com/search?image_filter=official&type=image), or a User
can sign an image with the commands [above](#signing-images-with-docker-content-trust)
, assuming they are stored in a private registry with signing data stored
within an attached [Notary Server](/engine/security/trust/deploying_notary/)
(Such as the Docker Trusted Registry).
using a container image from an unknown source, it will also prevent a user from
building a container image from a base layer from an unknown source. Trusted
sources could include Official Docker Images, found on the [Docker
Hub](https://hub.docker.com/search?image_filter=official&type=image), or User
trusted sources, with repositories and tags signed with the commands [above](#signing-images-with-docker-content-trust).
Engine Signature Verification prevents the following:
* `$ docker container run` of an unsigned image.
@ -246,10 +243,10 @@ unsigned images from being imported, loaded, or created.
### Enabling DCT within the Docker Enterprise Engine
DCT is controlled by the Docker Engine's configuration file. By default this is
found at `/etc/docker/daemon.json`. For more details on this file can be found
found at `/etc/docker/daemon.json`. More details on this file can be found
[here](/engine/reference/commandline/dockerd/#daemon-configuration-file)
The `content-trust` flag is based around, a `mode` variable instructing
The `content-trust` flag is based around a `mode` variable instructing
the engine whether to enforce signed images, and a `trust-pinning` variable
instructing the engine which sources to trust.
@ -258,10 +255,10 @@ instructing the engine which sources to trust.
* `Disabled` - Verification is not active and the remainder of the content-trust
related metadata will be ignored. This is the default value if `mode` is not
specified.
* `Permissive` - Verification will be performed, but only failures will only be
* `Permissive` - Verification will be performed, but only failures will be
logged and remain unenforced. This configuration is intended for testing of
changes related to content-trust. The results of the signature verification
is displayed in the Docker Engine daemon logs.
is displayed in the Docker Engine's daemon logs.
* `Enabled` - Content trust will be enforced and an image that cannot be
verified successfully will not be pulled or run.
@ -278,7 +275,7 @@ verified successfully will not be pulled or run.
All official Docker library images found on the Docker Hub (docker.io/library/*)
are signed by the same Notary root key. This root key's ID has been embedded
inside of the Docker Enterprise Engine. Therefore to enforce that only official
Docker images are used. Specify:
Docker images can be used. Specify:
```
{
@ -300,7 +297,7 @@ root key used to sign a repository (or rather its respective keys). This is the
root key on the host that originally signed the repository (i.e. your workstation).
This can be retrieved from the workstation that signed the repository through
`$ grep -r "root" ~/.docker/trust/private/` (Assuming your trust data is
at `~/.docker/trust/*`). It is expected that this canocial ID has initiated
at `~/.docker/trust/*`). It is expected that this canonical ID has initiated
multiple image repositories (`mydtr/user1/image1` and `mydtr/user1/image2`).
```
@ -324,16 +321,16 @@ $ grep -r "root" ~/.docker/trust/private
}
```
* Notary Root key ID (DCT Certitifcate ID) is an ID that describes the same, but
* Notary Root key ID (DCT Certificate ID) is an ID that describes the same, but
the ID is unique per repository. i.e `mydtr/user1/image1` and `mydtr/usr1/image2`
will have unique certitificate IDs. A certificate ID can be retrieved via a
`$ docker trust inspect` command is labelled as a root-key (referring back
will have unique certificate IDs. A certificate ID can be retrieved via a
`$ docker trust inspect` command and is labelled as a root-key (referring back
to the Notary key name). This is designed for when different users are signing
their own repositories, i.e. there is no central signing server. As a cert-id
is more granular, it would take priority if a conflict occurs over a root ID.
```
# Retrieving Cert ID
# Retrieving Cert ID
$ docker trust inspect mydtr/user1/repo1 | jq -r '.[].AdministrativeKeys[] | select(.Name=="Root") | .Keys[].ID'
9430d6e31e3b3e240957a1b62bbc2d436aafa33726d0fcb50addbf7e2dfa2168
@ -386,11 +383,12 @@ trust cached signature data. This is done through the
## Client Enforcement with Docker Content Trust
> Note this is supported on Docker CE and Enterprise Engine newer than 17.03
> Note this is supported on Docker Community and Enterprise Engines newer than
> 17.03.
Currently, content trust is disabled by default in the Docker Client. To enable
it, set the `DOCKER_CONTENT_TRUST` environment variable to `1`. This prevents
Users from working with tagged images unless they contain a signature.
users from working with tagged images unless they contain a signature.
When DCT is enabled in the Docker client, `docker` CLI commands that operate on
tagged images must either have content signatures or explicit content hashes.
@ -420,7 +418,7 @@ Status: Downloaded newer image for dtr.example.com/user/image@sha256:ee7491c9c31
## Related information
* [Manage keys for content trust](trust_key_mng.md)
* [Automation with content trust](trust_automation.md)
* [Delegations for content trust](trust_delegation.md)
* [Automation with content trust](trust_automation.md)
* [Manage keys for content trust](trust_key_mng.md)
* [Play in a content trust sandbox](trust_sandbox.md)

36
engine/security/trust/trust_automation.md
View File

@ -5,39 +5,41 @@ title: Automation with content trust
---
It is very common for Docker Content Trust to be built into existing automation
systems. To allow tools to wrap docker and push trusted content, there are
systems. To allow tools to wrap Docker and push trusted content, there are
environment variables that can be passed through to the client.
This guide follows the steps as [here](content_trust/#signing-images-with-docker-content-trust)
so please read that and understand the pre-requisites.
This guide follows the steps as described
[here](content_trust/#signing-images-with-docker-content-trust) so please read
that and understand its prerequisites.
When working directly with the Notary client, it uses its [own set of environment variables](/notary/reference/client-config.md#environment-variables-optional).
## Adding a Delegation's Private Key
## Adding a Delegation Private Key
To automate importing a delegation's private key to the local Docker trust store, we
need to pass a passphrase for the new key. This passphase will be required
everytime that delegator signs a tag.
To automate importing a delegation private key to the local Docker trust store, we
need to pass a passphrase for the new key. This passphrase will be required
everytime that delegation signs a tag.
```
$ export DOCKER_CONTENT_TRUST_REPOSITORY_PASSPHRASE="mypassphase123"
$ export DOCKER_CONTENT_TRUST_REPOSITORY_PASSPHRASE="mypassphrase123"
$ docker trust key load delegation.key --name jeff
Loading key from "delegation.key"...
Successfully imported key from delegation.key
```
## Adding a Delegation's Public Key
## Adding a Delegation Public Key
To automate the addition of a new delegator to the Repository, we need to pass
the passphrases for the workstations Root Key (Notary Canonical Root Key ID) and
the image repositories passphase (Notary Root key ID).
If you initialising a repository at the same time as adding a Delegation
public key, then you will need to use the local Notary Canonical Root Key's
passphrase to create the repositories trust data. If the repository has already
been initiated then you only need the repositories passphrase.
```
# Export the Local Root Key Passphrase
# Export the Local Root Key Passphrase if required.
$ export DOCKER_CONTENT_TRUST_ROOT_PASSPHRASE="rootpassphrase123"
# Export the Repository Passphase
# Export the Repository Passphrase
$ export DOCKER_CONTENT_TRUST_REPOSITORY_PASSPHRASE="repopassphrase123"
# Initialise Repo and Push Delegation
@ -52,10 +54,10 @@ Successfully added signer: dtr.example.com/admin/demo
Finally when signing an image, we will need to export the passphrase of the
signing key. This was created when the key was loaded into the local Docker
Store with `$ docker trust key load`.
trust store with `$ docker trust key load`.
```
$ export DOCKER_CONTENT_TRUST_REPOSITORY_PASSPHRASE="mypassphase123"
$ export DOCKER_CONTENT_TRUST_REPOSITORY_PASSPHRASE="mypassphrase123"
$ docker trust sign dtr.example.com/admin/demo:1
Signing and pushing trust data for local image dtr.example.com/admin/demo:1, may overwrite remote trust data
@ -101,7 +103,7 @@ unable to process Dockerfile: No trust data for notrust
## Related information
* [Delegations for content trust](trust_delegation.md)
* [Content trust in Docker](content_trust.md)
* [Manage keys for content trust](trust_key_mng.md)
* [Delegations for content trust](trust_delegation.md)
* [Play in a content trust sandbox](trust_sandbox.md)

467
engine/security/trust/trust_delegation.md
View File

@ -4,48 +4,74 @@ keywords: trust, security, delegations, keys, repository
title: Delegations for content trust
---
Docker Engine supports the usage of the `targets/releases` delegation as the
canonical source of a trusted image tag.
Delegations in Docker Content Trust 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.
Using this delegation allows you to collaborate with other publishers without
sharing your repository key, which is a combination of your targets and snapshot keys.
See [Manage keys for content trust](trust_key_mng.md) for more information).
Collaborators can keep their own delegation keys private.
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.
The `targets/releases` delegation is currently an optional feature - in order
to set up delegations, you must use the Notary CLI:
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.
1. [Download the client](https://github.com/theupdateframework/notary/releases)
## Configuring the Notary Cli
Some of the more advanced features of Docker Content Trust require the Notary
Cli. To install and configure the Notary Cli follow:
1) Download the [client](https://github.com/theupdateframework/notary/releases)
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:
```
{
"trust_dir" : "~/.docker/trust",
"remote_server": {
"url": "https://notary.docker.io"
}
}
```
```
{
"trust_dir" : "~/.docker/trust",
"remote_server": {
"url": "https://dtr.example.com"
"root_ca": "../.docker/ca.pem"
}
}
```
This tells Notary where the Docker Content Trust data is stored, and to use the
Notary server used for images in Docker Hub.
This configuration file will tell Notary where the local Docker Trust data is
stored, as well as which Notary server to use by default.
For more detailed information about how to use Notary outside of the default
Docker Content Trust use cases, refer to the
[Notary CLI documentation](/notary/getting_started.md).
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)
When publishing and listing delegation changes using the Notary client,
your Docker Hub credentials are required.
## Creating Delegation Keys
## Generating delegation keys
A prerequisite to adding your first contributor is a pair of delegation keys.
These keys can either be generated locally using `$ docker trust`, generated by
a certificate authority, or can be taken from a Universal Control Plane's
[Client Bundle](ee/ucp/user-access/cli/#download-client-certificates).
Your collaborator needs to generate a private key (either RSA or ECDSA)
and give you the public key so that you can add it to the `targets/releases`
delegation.
### Using Docker Trust to Generate Keys
Docker trust has a built in generator for a delegation key pair,
`$ docker trust generate <name>`, running this command will automatically load
the delegation private key in to the local Docker trust store.
```
$ docker trust key generate jeff
Generating key for jeff...
Enter passphrase for new jeff key with ID 9deed25:
Repeat passphrase for new jeff key with ID 9deed25:
Successfully generated and loaded private key. Corresponding public key available: /home/ubuntu/Documents/mytrustdir/jeff.pub
```
### Manually Generating Keys
If you need to manually generate a private key (either RSA or ECDSA) and a x509
certificate containing the public key, you can use local tools like openssl or
cfssl along with a local or company wide Certificate Authority.
The easiest way for them to generate these keys is with OpenSSL.
Here is an example of how to generate a 2048-bit RSA portion key (all RSA keys
must be at least 2048 bits):
@ -79,137 +105,340 @@ $ openssl x509 -req -sha256 -days 365 -in delegation.csr -signkey delegation.key
Then they need to give you `delegation.crt`, whether it is self-signed or signed
by a CA.
## Adding a delegation key to an existing repository
If your repository was created using a version of Docker Engine prior to 1.11,
then before adding any delegations, you should rotate the snapshot key to the server
so that collaborators don't need your snapshot key to sign and publish tags:
Finally you will need to add the private key into your local Docker trust store.
```
$ notary key rotate docker.io/<username>/<imagename> snapshot -r
$ docker trust key load delegation.key --name jeff
Loading key from "delegation.key"...
Enter passphrase for new jeff key with ID 8ae710e:
Repeat passphrase for new jeff key with ID 8ae710e:
Successfully imported key from delegation.key
```
This tells Notary to rotate a key for your particular image repository. The
`docker.io/` prefix is required. `snapshot -r` specifies that you want
to rotate the snapshot key and that you want the server to manage it (`-r`
stands for "remote").
### Using Universal Control Plane's Client Bundles
When adding a delegation, your must acquire
[the PEM-encoded x509 certificate with the public key](#generating-delegation-keys)
of the collaborator you wish to delegate to.
Universal Control Plane manages cli and api access to its clusters through
certificates generated in a Client Bundle. These certificates and keys can be
used as a delegation key pair. Within each client bundle there is a unique
private key (`key.pem`) and x509 certificate containing a public key
(`cert.pem`).
Assuming you have the certificate `delegation.crt`, you can add a delegation
for this user and then publish the delegation change:
1) Download a user's client bundle from the
[Universal Control Plane](ee/ucp/user-access/cli/#download-client-certificates).
2) Extract the client bundle into your current directory
3) Load the private key into your local Docker trust store
```
$ notary delegation add docker.io/<username>/<imagename> targets/releases delegation.crt --all-paths
$ notary publish docker.io/<username>/<imagename>
$ docker trust key load key.pem --name jeff
Loading key from "key.pem"...
Enter passphrase for new jeff key with ID 9deed25:
Repeat passphrase for new jeff key with ID 9deed25:
Successfully imported key from key.pem
```
The preceding example illustrates a request to add the delegation
`targets/releases` to the image repository, if it doesn't exist. Be sure to use
`targets/releases` - Notary supports multiple delegation roles, so if you mistype
the delegation name, the Notary CLI does not error. However, Docker Engine
supports reading only from `targets/releases`.
### Viewing local Delegation keys
It also adds the collaborator's public key to the delegation, enabling them to sign
the `targets/releases` delegation so long as they have the private key corresponding
to this public key. The `--all-paths` flag tells Notary not to restrict the tag
names that can be signed into `targets/releases`, which we highly recommend for
`targets/releases`.
Publishing the changes tells the server about the changes to the `targets/releases`
delegation.
After publishing, view the delegation information to ensure that you correctly added
the keys to `targets/releases`:
To list the keys that have been imported in to the local Docker trust store we
can use the Notary cli.
```
$ notary delegation list docker.io/<username>/<imagename>
$ notary key list
ROLE PATHS KEY IDS THRESHOLD
---------------------------------------------------------------------------------------------------------------
targets/releases "" <all paths> 729c7094a8210fd1e780e7b17b7bb55c9a28a48b871b07f65d97baf93898523a 1
ROLE GUN KEY ID LOCATION
---- --- ------ --------
root f6c6a4b00fefd8751f86194c7d87a3bede444540eb3378c4a11ce10852ab1f96 /home/ubuntu/.docker/trust/private
jeff 9deed251daa1aa6f9d5f9b752847647cf8d705da0763aa5467650d0987ed5306 /home/ubuntu/.docker/trust/private
```
You can see the `targets/releases` with its paths and the key ID you just added.
## Managing Delegations in a Notary Server
Notary currently does not map collaborators names to keys, so we recommend
that you add and list delegation keys one at a time, and keep a mapping of the key
IDs to collaborators yourself should you need to remove a collaborator.
Docker Content Trust handles initiating a repository with trust data for you,
including rotating low level keys like the target and the snapshot key to the
remote Notary server. This is all done the first time you add a delegation
public key to the Notary server.
## Removing a delegation key from an existing repository
When initiating a repository you will need the key and the passphrase of a local
Notary Canonical Root Key. If you have not initiated a repository before, and
therefore don't have a Notary root key, `$ docker trust` will create one for you.
To revoke a collaborator's ability to sign tags for your image repository, you
need to remove their keys from the `targets/releases` delegation. To do this,
you need the IDs of their keys.
> Be sure to protect your [Notary Canonical Root Key](./trust_key_mng.md)
```bash
$ notary delegation remove docker.io/<username>/<imagename> targets/releases 729c7094a8210fd1e780e7b17b7bb55c9a28a48b871b07f65d97baf93898523a
### Initiating the Repository
Removal of delegation role targets/releases with keys [729c7094a8210fd1e780e7b17b7bb55c9a28a48b871b07f65d97baf93898523a], to repository "docker.io/<username>/<imagename>" staged for next publish.
```
To upload the first key to a delegation, at the same time initiating a
repository, you can use the `$ docker trust signer add` command. This will add
the contributor's public key to the `targets/releases` delegation, and create a
second `targets/<name>` delegation.
The revocation takes effect as soon as you publish:
For Docker Content Trust the name of the second delegation, in the below example
`jeff`, is there to help you keep track of the owner of the keys. In more
advanced use cases of Notary additional delegations are used for hierarchy.
```
$ notary publish docker.io/<username>/<imagename>
$ docker trust signer add --key cert.pem jeff dtr.example.com/admin/demo
Adding signer "jeff" to dtr.example.com/admin/demo...
Initializing signed repository for dtr.example.com/admin/demo...
Enter passphrase for root key with ID f6c6a4b:
Enter passphrase for new repository key with ID b0014f8:
Repeat passphrase for new repository key with ID b0014f8:
Successfully initialized "dtr.example.com/admin/demo"
Successfully added signer: jeff to dtr.example.com/admin/demo
```
By removing all the keys from the `targets/releases` delegation, the
delegation (and any tags that are signed into it) is removed. That means that
these tags are all deleted, and you may end up with older, legacy tags that
were signed directly by the targets key.
## Removing the `targets/releases` delegation entirely from a repository
If you've decided that delegations aren't for you, you can delete the
`targets/releases` delegation entirely. This also removes all the tags that
are currently in `targets/releases`, however, and you may end up with older,
legacy tags that were signed directly by the targets key.
To delete the `targets/releases` delegation:
You can see which keys have been pushed to the Notary server for each repository
with the `$ docker trust inspect` command.
```
$ notary delegation remove docker.io/<username>/<imagename> targets/releases
$ docker trust inspect --pretty dtr.example.com/admin/demo
Are you sure you want to remove all data for this delegation? (yes/no)
yes
No signatures for dtr.example.com/admin/demo
Forced removal (including all keys and paths) of delegation role targets/releases to repository "docker.io/<username>/<imagename>" staged for next publish.
$ notary publish docker.io/<username>/<imagename>
List of signers and their keys for dtr.example.com/admin/demo
SIGNER KEYS
jeff 1091060d7bfd
Administrative keys for dtr.example.com/admin/demo
Repository Key: b0014f8e4863df2d028095b74efcb05d872c3591de0af06652944e310d96598d
Root Key: 64d147e59e44870311dd2d80b9f7840039115ef3dfa5008127d769a5f657a5d7
```
## Pushing trusted data as a collaborator
As a collaborator with a private key that has been added to a repository's
`targets/releases` delegation, you need to import the private key that you
generated into Content Trust.
To do so, you can run:
You could also use the Notary cli to list delegations and keys. Here you can
clearly see the keys were attached to `targets/releases` and `targets/jeff`.
```
$ notary key import delegation.key --role user
$ notary delegation list dtr.example.com/admin/demo
ROLE PATHS KEY IDS THRESHOLD
---- ----- ------- ---------
targets/jeff "" <all paths> 1091060d7bfd938dfa5be703fa057974f9322a4faef6f580334f3d6df44c02d1 1
targets/releases "" <all paths> 1091060d7bfd938dfa5be703fa057974f9322a4faef6f580334f3d6df44c02d1 1
```
where `delegation.key` is the file containing your PEM-encoded private key.
### Adding Additional Signers
After you have done so, running `docker push` on any repository that
includes your key in the `targets/releases` delegation automatically signs
tags using this imported key.
Docker Trust allows you to configure multiple delegations per repository,
allowing you to manage the lifecycle of delegations. When adding additional
delegations with `$ docker trust` the collaborators key is once again added to
the `targets/release` role.
## `docker push` behavior
> Note you will need the passphrase for the repository key, this would have been
> configured when you first initiated the repository.
When running `docker push` with Docker Content Trust, Docker Engine
attempts to sign and push with the `targets/releases` delegation if it exists.
If it does not, the targets key is used to sign the tag, if the key is available.
```
$ docker trust signer add --key ben.pub ben dtr.example.com/admin/demo
Adding signer "ben" to dtr.example.com/admin/demo...
Enter passphrase for repository key with ID b0014f8:
Successfully added signer: ben to dtr.example.com/admin/demo
```
## `docker pull` and `docker build` behavior
Check to prove that there are now 2 delegations (Signer).
When running `docker pull` or `docker build` with Docker Content Trust, Docker
Engine pulls tags only signed by the `targets/releases` delegation role or
the legacy tags that were signed directly with the `targets` key.
```
$ docker trust inspect --pretty dtr.example.com/admin/demo
No signatures for dtr.example.com/admin/demo
List of signers and their keys for dtr.example.com/admin/demo
SIGNER KEYS
ben afa404703b25
jeff 1091060d7bfd
Administrative keys for dtr.example.com/admin/demo
Repository Key: b0014f8e4863df2d028095b74efcb05d872c3591de0af06652944e310d96598d
Root Key: 64d147e59e44870311dd2d80b9f7840039115ef3dfa5008127d769a5f657a5d7
```
### Adding Keys to an Existing Delegation
To support things like key rotation and expiring / retiring keys you can publish
multiple contributor keys per delegation. The only prerequisite here is to make
sure you use the same the delegation name, in this case `jeff`. Docker trust
will automatically handle adding this new key to `targets/releases`.
> Note you will need the passphrase for the repository key, this would have been
> configured when you first initiated the repository.
```
$ docker trust signer add --key cert2.pem jeff dtr.example.com/admin/demo
Adding signer "jeff" to dtr.example.com/admin/demo...
Enter passphrase for repository key with ID b0014f8:
Successfully added signer: jeff to dtr.example.com/admin/demo
```
Check to prove that the delegation (Signer) now contains multiple Key IDs.
```
$ docker trust inspect --pretty dtr.example.com/admin/demo
No signatures for dtr.example.com/admin/demo
List of signers and their keys for dtr.example.com/admin/demo
SIGNER KEYS
jeff 1091060d7bfd, 5570b88df073
Administrative keys for dtr.example.com/admin/demo
Repository Key: b0014f8e4863df2d028095b74efcb05d872c3591de0af06652944e310d96598d
Root Key: 64d147e59e44870311dd2d80b9f7840039115ef3dfa5008127d769a5f657a5d7
```
### Removing a Delegation
If you need to remove a delegation, including the contributor keys that are
attached to the `targets/releases` role, you can use the
`$ docker trust signer remove` command.
> Note tags that were signed by the removed delegation will need to be resigned
> by an active delegation
```
$ docker trust signer remove dtr.example.com/admin/demo
Removing signer "ben" from dtr.example.com/admin/demo...
Enter passphrase for repository key with ID b0014f8:
Successfully removed ben from dtr.example.com/admin/demo
```
#### Troubleshooting
1) If you see an error that there are no useable keys in `targets/releases`. You
will need to add additional delegations using `docker trust signer add` before
resigning images.
```
WARN[0000] role targets/releases has fewer keys than its threshold of 1; it will not be usable until keys are added to it
```
2) If you have added additional delegations already and are seeing an error
message that there are no valid signatures in `targest/releases`. You will need
to resign the `targets/releases` delegation file with the Notary Cli.
```
WARN[0000] Error getting targets/releases: valid signatures did not meet threshold for targets/releases
```
Resigning the delegation file is done with the `$ notary witness` command
```
$ notary witness dtr.example.com/admin/demo targets/releases --publish
```
More information on the `$ notary witness` command can be found
[here](https://github.com/theupdateframework/notary/blob/master/docs/advanced_usage.md#recovering-a-delegation)
### Removing a Contributor's Key from a Delegation
As part of rotating keys for a delegation, you may want to remove an individual
key but retain the delegation. This can be done with the Notary cli.
Remember you will have to remove the key from both the `targets/releases` role
and the role specific to that signer `targets/<name>`.
1) We will need to grab the Key ID from the Notary Server
```
$ notary delegation list dtr.example.com/admin/demo
ROLE PATHS KEY IDS THRESHOLD
---- ----- ------- ---------
targets/jeff "" <all paths> 8fb597cbaf196f0781628b2f52bff6b3912e4e8075720378fda60d17232bbcf9 1
1091060d7bfd938dfa5be703fa057974f9322a4faef6f580334f3d6df44c02d1
targets/releases "" <all paths> 8fb597cbaf196f0781628b2f52bff6b3912e4e8075720378fda60d17232bbcf9 1
1091060d7bfd938dfa5be703fa057974f9322a4faef6f580334f3d6df44c02d1
```
2) Remove from the `targets/releases` delegation
```
$ notary delegation remove dtr.example.com/admin/demo targets/targets 1091060d7bfd938dfa5be703fa057974f9322a4faef6f580334f3d6df44c02d1 --publish
Auto-publishing changes to dtr.example.com/admin/demo
Enter username: admin
Enter password:
Enter passphrase for targets key with ID b0014f8:
Successfully published changes for repository dtr.example.com/admin/demo
```
3) Remove from the `targets/<name>` delegation
```
$ notary delegation remove dtr.example.com/admin/demo targets/jeff 1091060d7bfd938dfa5be703fa057974f9322a4faef6f580334f3d6df44c02d1 --publish
Removal of delegation role targets/jeff with keys [5570b88df0736c468493247a07e235e35cf3641270c944d0e9e8899922fc6f99], to repository "dtr.example.com/admin/demo" staged for next publish.
Auto-publishing changes to dtr.example.com/admin/demo
Enter username: admin
Enter password:
Enter passphrase for targets key with ID b0014f8:
Successfully published changes for repository dtr.example.com/admin/demo
```
4) Check the remaining delegation list
```
$ notary delegation list dtr.example.com/admin/demo
ROLE PATHS KEY IDS THRESHOLD
---- ----- ------- ---------
targets/jeff "" <all paths> 8fb597cbaf196f0781628b2f52bff6b3912e4e8075720378fda60d17232bbcf9 1
targets/releases "" <all paths> 8fb597cbaf196f0781628b2f52bff6b3912e4e8075720378fda60d17232bbcf9 1
```
### Removing a local Delegation Private Key
As part of rotating delegation keys, you may need to remove a local delegation
key from the local Docker trust store. This is done with the Notary cli, using
the `$ notary key remove` command.
1) We will need to get the Key ID from the local Docker Trust store
```
$ notary key list
ROLE GUN KEY ID LOCATION
---- --- ------ --------
root f6c6a4b00fefd8751f86194c7d87a3bede444540eb3378c4a11ce10852ab1f96 /home/ubuntu/.docker/trust/private
admin 8fb597cbaf196f0781628b2f52bff6b3912e4e8075720378fda60d17232bbcf9 /home/ubuntu/.docker/trust/private
jeff 1091060d7bfd938dfa5be703fa057974f9322a4faef6f580334f3d6df44c02d1 /home/ubuntu/.docker/trust/private
targets ...example.com/admin/demo c819f2eda8fba2810ec6a7f95f051c90276c87fddfc3039058856fad061c009d /home/ubuntu/.docker/trust/private
```
2) Remove the key from the local Docker Trust store
```
$ notary key remove 1091060d7bfd938dfa5be703fa057974f9322a4faef6f580334f3d6df44c02d1
Are you sure you want to remove 1091060d7bfd938dfa5be703fa057974f9322a4faef6f580334f3d6df44c02d1 (role jeff) from /home/ubuntu/.docker/trust/private? (yes/no) y
Deleted 1091060d7bfd938dfa5be703fa057974f9322a4faef6f580334f3d6df44c02d1 (role jeff) from /home/ubuntu/.docker/trust/private.
```
## Removing all trust data from a Repository
You can remove all trust data from a repository, including repository, target,
snapshot and all delegations keys using the Notary cli.
This is often required by a container registry before a particular repository
can be deleted.
```
$ notary delete dtr.example.com/admin/demo --remote
Deleting trust data for repository dtr.example.com/admin/demo
Enter username: admin
Enter password:
Successfully deleted local and remote trust data for repository dtr.example.com/admin/demo
$ docker trust inspect --pretty dtr.example.com/admin/demo
No signatures or cannot access dtr.example.com/admin/demo
```
## Related information