mirror of https://github.com/docker/docs.git
Remove EE "trust pinning" section
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
This commit is contained in:
Sebastiaan van Stijn
parent
36d0938bb2
commit
021e13a5ed
|
|
@ -100,8 +100,7 @@ read how to [manage keys for DCT](trust_key_mng.md).
|
|||
## Signing Images with Docker Content Trust
|
||||
|
||||
> **Note:**
|
||||
> This applies to Docker Community Engine 17.12 and newer, and Docker
|
||||
> Enterprise Engine 18.03 and newer.
|
||||
> This applies to Docker Community Engine 17.12 and newer.
|
||||
|
||||
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
|
||||
|
|
@ -213,188 +212,9 @@ Enter passphrase for signer key with ID 8ae710e:
|
|||
Successfully deleted signature for registry.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 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 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 or altered image.
|
||||
* `$ docker pull` of an unsigned or altered image.
|
||||
* `$ docker build` where the `FROM` image is not signed or is not scratch.
|
||||
|
||||
> **Note:**
|
||||
> The implicit pulls and runs performed by worker
|
||||
> nodes for a [Swarm service](../../swarm/services.md) on `$ docker service create` and
|
||||
> `$ docker service update` are also verified. Tag resolution of services
|
||||
> requires that all nodes in the Swarm including managers have content trust
|
||||
> enabled and similarly configured.
|
||||
|
||||
DCT does not verify that a running container’s filesystem has not been altered
|
||||
from what was in the image. For example, it does not prevent a container from
|
||||
writing to the filesystem, once the container is running. Moreover, it does not
|
||||
prevent the image's filesystem from being altered on a docker host's disk. DCT
|
||||
will also not prevent 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`. More details on this file can be found
|
||||
[here](/engine/reference/commandline/dockerd/#daemon-configuration-file).
|
||||
|
||||
> **Note:**
|
||||
> This configuration can be set on Linux machines **only**.
|
||||
|
||||
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.
|
||||
|
||||
`Mode` can take three variables:
|
||||
|
||||
* `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 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's daemon logs.
|
||||
* `Enforced` - Content trust will be enforced and an image that cannot be
|
||||
verified successfully will not be pulled or run.
|
||||
|
||||
```
|
||||
{
|
||||
"content-trust": {
|
||||
"mode": "enforced"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Official Docker images
|
||||
|
||||
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 can be used. Specify:
|
||||
|
||||
```
|
||||
{
|
||||
"content-trust": {
|
||||
"trust-pinning": {
|
||||
"official-library-images": true
|
||||
},
|
||||
"mode": "enforced"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### User-Signed images
|
||||
|
||||
There are two options for trust pinning user-signed images:
|
||||
|
||||
* Notary Canonical Root Key ID (DCT Root Key) is an ID that describes *just* the
|
||||
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 canonical ID has initiated
|
||||
multiple image repositories (`mydtr/user1/image1` and `mydtr/user1/image2`).
|
||||
|
||||
```
|
||||
# Retrieving Root ID
|
||||
$ grep -r "root" ~/.docker/trust/private
|
||||
/home/ubuntu/.docker/trust/private/0b6101527b2ac766702e4b40aa2391805b70e5031c04714c748f914e89014403.key:role: root
|
||||
|
||||
# Using a Canonical ID that has signed 2 repos (mydtr/user1/repo1 and mydtr/user1/repo2). Note you can use a Wildcard.
|
||||
|
||||
{
|
||||
"content-trust": {
|
||||
"trust-pinning": {
|
||||
"root-keys": {
|
||||
"mydtr/user1/*": [
|
||||
"0b6101527b2ac766702e4b40aa2391805b70e5031c04714c748f914e89014403"
|
||||
]
|
||||
}
|
||||
},
|
||||
"mode": "enforced"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
* Notary Root key ID (DCT Certificate ID) is an ID that describes the same, but
|
||||
the ID is unique per repository. For example, `mydtr/user1/image1` and `mydtr/usr1/image2`
|
||||
will have unique certificate IDs. A certificate ID can be retrieved through 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, for example, when 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
|
||||
$ docker trust inspect mydtr/user1/repo1 | jq -r '.[].AdministrativeKeys[] | select(.Name=="Root") | .Keys[].ID'
|
||||
9430d6e31e3b3e240957a1b62bbc2d436aafa33726d0fcb50addbf7e2dfa2168
|
||||
|
||||
# Using Cert Ids, by specifying 2 repositories by their DCT root ID. Example for using this may be different DTRs or maybe because the repository was initiated on different hosts, therefore having different canonical IDs.
|
||||
|
||||
{
|
||||
"content-trust": {
|
||||
"trust-pinning": {
|
||||
"cert-ids": {
|
||||
"mydtr/user1/repo1": [
|
||||
"9430d6e31e3b3e240957a1b62bbc2d436aafa33726d0fcb50addbf7e2dfa2168"
|
||||
],
|
||||
"mydtr/user2/repo1": [
|
||||
"544cf09f294860f9d5bc953ad80b386063357fd206b37b541bb2c54166f38d08"
|
||||
]
|
||||
}
|
||||
},
|
||||
"mode": "enforced"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Using DCT in an offline environment
|
||||
|
||||
If your engine is unable to communicate to the registry, we can enable DCT to
|
||||
trust cached signature data. This is done through the
|
||||
`allow-expired-cached-trust-data` variable.
|
||||
|
||||
```
|
||||
{
|
||||
"content-trust": {
|
||||
"trust-pinning": {
|
||||
"official-library-images": true,
|
||||
"root-keys": {
|
||||
"mydtr/user1/*": [
|
||||
"0b6101527b2ac766702e4b40aa2391805b70e5031c04714c748f914e89014403"
|
||||
]
|
||||
},
|
||||
"cert-ids": {
|
||||
"mydtr/user2/repo1": [
|
||||
"9430d6e31e3b3e240957a1b62bbc2d436aafa33726d0fcb50addbf7e2dfa2168"
|
||||
],
|
||||
}
|
||||
},
|
||||
"mode": "enforced",
|
||||
"allow-expired-cached-trust-data": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Client Enforcement with Docker Content Trust
|
||||
|
||||
> 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
|
||||
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.
|
||||
|
||||
|
|
|
|||
|
|
@ -8,8 +8,6 @@ This document describes basic use of the Notary CLI as a tool supporting Docker
|
|||
Content Trust. For more advanced use cases, you must
|
||||
[run your own Notary service](running_a_service.md). Read the
|
||||
[use the Notary client for advanced users](advanced_usage.md) documentation.
|
||||
> **Warning**: Assistance with the open-source notary client or server is not provided by
|
||||
Docker Enterprise Customer Support.
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue