kotovalexarian-likes-github/moby--moby
1
0
Fork 0
mirror of https://github.com/moby/moby.git synced 2022-11-09 12:21:53 -05:00
Code Releases Activity

Changing docs to reflect new names

Browse source 
Signed-off-by: Diogo Monica <diogo@docker.com>
This commit is contained in:
Diogo Monica 2015-10-09 12:14:46 -07:00
parent 63f8db83aa
commit d9a2fadb5e
7 changed files with 84 additions and 76 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

9
api/client/trust.go
View file

@ -197,14 +197,17 @@ func (cli *DockerCli) getPassphraseRetriever() passphrase.Retriever {
}
// Backwards compatibility with old env names. We should remove this in 1.10
if env["root"] == "" {
env["root"] = os.Getenv("DOCKER_CONTENT_TRUST_OFFLINE_PASSPHRASE")
fmt.Fprintf(cli.err, "[DEPRECATED] The environment variable DOCKER_CONTENT_TRUST_OFFLINE_PASSPHRASE has been deprecated and will be removed in v1.10. Please use DOCKER_CONTENT_TRUST_ROOT_PASSPHRASE\n")
}
if env["snapshot"] == "" || env["targets"] == "" {
env["snapshot"] = os.Getenv("DOCKER_CONTENT_TRUST_TAGGING_PASSPHRASE")
env["targets"] = os.Getenv("DOCKER_CONTENT_TRUST_TAGGING_PASSPHRASE")
fmt.Fprintf(cli.err, "[DEPRECATED] The environment variable DOCKER_CONTENT_TRUST_TAGGING_PASSPHRASE has been deprecated and will be removed in v1.10. Please use DOCKER_CONTENT_TRUST_REPOSITORY_PASSPHRASE\n")
}
if env["root"] == "" {
env["root"] = os.Getenv("DOCKER_CONTENT_TRUST_OFFLINE_PASSPHRASE")
}
return func(keyName string, alias string, createNew bool, numAttempts int) (string, bool, error) {
if v := env[alias]; v != "" {

5
docs/misc/deprecated.md
View file

@ -105,4 +105,9 @@ the path does not exist.
Version 1.9 adds a flag (`--disable-legacy-registry=false`) which prevents the docker daemon from `pull`, `push`, and `login` operations against v1 registries. Though disabled by default, this signals the intent to deprecate the v1 protocol.
### Docker Content Trust ENV passphrase variables name change
As of 1.9, Docker Content Trust Offline key will be renamed to Root key and the Tagging key will be renamed to Repository key. Due to this renaming, we're also changing the corresponding environment variables
- DOCKER_CONTENT_TRUST_OFFLINE_PASSPHRASE will now be named DOCKER_CONTENT_TRUST_ROOT_PASSPHRASE
- DOCKER_CONTENT_TRUST_TAGGING_PASSPHRASE will now be named DOCKER_CONTENT_TRUST_REPOSITORY_PASSPHRASE

42
docs/security/trust/content_trust.md
View file

@ -106,12 +106,12 @@ $ docker pull someimage@sha256:d149ab53f8718e987c3a3024bb8aa0e2caadf6c0328f1d9d8
Trust for an image tag is managed through the use of signing keys. A key set is
created when an operation using content trust is first invoked. Docker's content
trust makes use of four different keys:
trust makes use of four different keys:
| Key | Description |
|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| offline key | Root of content trust for a image tag. When content trust is enabled, you create the offline key once. |
| target and snapshot | These two keys are known together as the "tagging" key. When content trust is enabled, you create this key when you add a new image repository. If you have the offline key, you can export the tagging key and allow other publishers to sign the image tags. |
| root key | Root of content trust for a image tag. When content trust is enabled, you create the root key once. |
| 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. |
| 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. |
With the exception of the timestamp, all the keys are generated and stored locally
@ -123,16 +123,16 @@ The following image depicts the various signing keys and their relationships:
![Content trust components](../images/trust_components.png)
>**WARNING**: Loss of the offline key is **very difficult** to recover from.
>**WARNING**: Loss of the root key is **very difficult** to recover from.
>Correcting this loss requires intervention from [Docker
>Support](https://support.docker.com) to reset the repository state. This loss
>also requires **manual intervention** from every consumer that used a signed
>tag from this repository prior to the loss.
You should backup the offline key somewhere safe. Given that it is only required
You should backup the root key somewhere safe. Given that it is only required
to create new repositories, it is a good idea to store it offline. Make sure you
read [Manage keys for content trust](/security/trust/trust_key_mng) information
for details on securing, and backing up your keys.
for details on securing, and backing up your keys.
## Survey of typical content trust operations
@ -185,27 +185,27 @@ The push refers to a repository [docker.io/docker/trusttest] (len: 1)
902b87aaaec9: Image already exists
latest: digest: sha256:d02adacee0ac7a5be140adb94fa1dae64f4e71a68696e7f8e7cbf9db8dd49418 size: 3220
Signing and pushing trust metadata
You are about to create a new offline signing key passphrase. This passphrase
You are about to create a new root signing key passphrase. This passphrase
will be used to protect the most sensitive key in your signing system. Please
choose a long, complex passphrase and be careful to keep the password and the
key file itself secure and backed up. It is highly recommended that you use a
password manager to generate the passphrase and keep it safe. There will be no
way to recover this key. You can find the key in your config directory.
Enter passphrase for new offline key with id a1d96fb:
Repeat passphrase for new offline key with id a1d96fb:
Enter passphrase for new tagging key with id docker.io/docker/trusttest (3a932f1):
Repeat passphrase for new tagging key with id docker.io/docker/trusttest (3a932f1):
Enter passphrase for new root key with id a1d96fb:
Repeat passphrase for new root key with id a1d96fb:
Enter passphrase for new repository key with id docker.io/docker/trusttest (3a932f1):
Repeat passphrase for new repository key with id docker.io/docker/trusttest (3a932f1):
Finished initializing "docker.io/docker/trusttest"
```
When you push your first tagged image with content trust enabled, the `docker`
client recognizes this is your first push and:
- alerts you that it will create a new offline key
- alerts you that it will create a new root key
- requests a passphrase for the key
- generates an offline key in the `~/.docker/trust` directory
- generates a tagging key for in the `~/.docker/trust` directory
- generates a root key in the `~/.docker/trust` directory
- generates a repository key for in the `~/.docker/trust` directory
The passphrase you chose for both the offline key and your content key-pair
The passphrase you chose for both the root key and your content key-pair
should be randomly generated and stored in a *password manager*.
> **NOTE**: If you omit the `latest` tag, content trust is skipped. This is true
@ -223,8 +223,8 @@ No tag specified, skipping trust metadata push
It is skipped because as the message states, you did not supply an image `TAG`
value. In Docker content trust, signatures are associated with tags.
Once you have an offline key on your system, subsequent images repositories
you create can use that same offline key:
Once you have a root key on your system, subsequent images repositories
you create can use that same root key:
```bash
$ docker push docker.io/docker/seaside:latest
@ -233,13 +233,13 @@ a9539b34a6ab: Image successfully pushed
b3dbab3810fc: Image successfully pushed
latest: digest: sha256:d2ba1e603661a59940bfad7072eba698b79a8b20ccbb4e3bfb6f9e367ea43939 size: 3346
Signing and pushing trust metadata
Enter key passphrase for offline key with id a1d96fb:
Enter passphrase for new tagging key with id docker.io/docker/seaside (bb045e3):
Repeat passphrase for new tagging key with id docker.io/docker/seaside (bb045e3):
Enter key passphrase for root key with id a1d96fb:
Enter passphrase for new repository key with id docker.io/docker/seaside (bb045e3):
Repeat passphrase for new repository key with id docker.io/docker/seaside (bb045e3):
Finished initializing "docker.io/docker/seaside"
```
The new image has its own tagging key and timestamp key. The `latest` tag is signed with both of
The new image has its own repository key and timestamp key. The `latest` tag is signed with both of
these.

12
docs/security/trust/trust_automation.md
View file

@ -18,16 +18,16 @@ To allow tools to wrap docker and push trusted content, there are two
environment variables that allow you to provide the passphrases without an
expect script, or typing them in:
- `DOCKER_CONTENT_TRUST_OFFLINE_PASSPHRASE`
- `DOCKER_CONTENT_TRUST_TAGGING_PASSPHRASE`
- `DOCKER_CONTENT_TRUST_ROOT_PASSPHRASE`
- `DOCKER_CONTENT_TRUST_REPOSITORY_PASSPHRASE`
Docker attempts to use the contents of these environment variables as passphrase
for the keys. For example, an image publisher can export the repository `target`
and `snapshot` passphrases:
```bash
$ export DOCKER_CONTENT_TRUST_OFFLINE_PASSPHRASE="u7pEQcGoebUHm6LHe6"
$ export DOCKER_CONTENT_TRUST_TAGGING_PASSPHRASE="l7pEQcTKJjUHm6Lpe4"
$ export DOCKER_CONTENT_TRUST_ROOT_PASSPHRASE="u7pEQcGoebUHm6LHe6"
$ export DOCKER_CONTENT_TRUST_REPOSITORY_PASSPHRASE="l7pEQcTKJjUHm6Lpe4"
```
Then, when pushing a new tag the Docker client does not request these values but signs automatically:
@ -43,7 +43,7 @@ Signing and pushing trust metadata
## Building with content trust
You can also build with content trust. Before running the `docker build` command, you should set the environment variable `DOCKER_CONTENT_TRUST` either manually or in in a scripted fashion. Consider the simple Dockerfile below.
You can also build with content trust. Before running the `docker build` command, you should set the environment variable `DOCKER_CONTENT_TRUST` either manually or in in a scripted fashion. Consider the simple Dockerfile below.
```Dockerfile
FROM docker/trusttest:latest
@ -73,7 +73,7 @@ unable to process Dockerfile: No trust data for notrust
## Related information
* [Content trust in Docker](/security/trust/content_trust)
* [Content trust in Docker](/security/trust/content_trust)
* [Manage keys for content trust](/security/trust/trust_key_mng)
* [Play in a content trust sandbox](/security/trust/trust_sandbox)

20
docs/security/trust/trust_key_mng.md
View file

@ -11,12 +11,12 @@ parent= "smn_content_trust"
# Manage keys for content trust
Trust for an image tag is managed through the use of keys. Docker's content
trust makes use four different keys:
trust makes use four different keys:
| Key | Description |
|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| offline key | Root of content trust for a image tag. When content trust is enabled, you create the offline key once. |
| target and snapshot | These two keys are known together as the "tagging" key. When content trust is enabled, you create this key when you add a new image repository. If you have the offline key, you can export the tagging key and allow other publishers to sign the image tags. |
| root key | Root of content trust for a image tag. When content trust is enabled, you create the root key once. |
| 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. |
| 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. |
With the exception of the timestamp, all the keys are generated and stored locally
@ -26,11 +26,11 @@ service that isn't directly exposed to the internet and are encrypted at rest.
## Choosing a passphrase
The passphrases you chose for both the offline key and your tagging key should
be randomly generated and stored in a password manager. Having the tagging key
The passphrases you chose for both the root key and your repository key should
be randomly generated and stored in a password manager. Having the repository key
allow users to sign image tags on a repository. Passphrases are used to encrypt
your keys at rest and ensures that a lost laptop or an unintended backup doesn't
put the private key material at risk.
put the private key material at risk.
## Back up your keys
@ -39,7 +39,7 @@ on creation. Even so, you should still take care of the location where you back
Good practice is to create two encrypted USB keys.
It is very important that you backup your keys to a safe, secure location. Loss
of the tagging key is recoverable; loss of the offline key is not.
of the repository key is recoverable; loss of the root key is not.
The Docker client stores the keys in the `~/.docker/trust/private` directory.
Before backing them up, you should `tar` them into an archive:
@ -53,7 +53,7 @@ $ umask 077; tar -zcvf private_keys_backup.tar.gz ~/.docker/trust/private; umask
If a publisher loses keys it means losing the ability to sign trusted content for
your repositories. If you lose a key, contact [Docker
Support](https://support.docker.com) (support@docker.com) to reset the repository
state.
state.
This loss also requires **manual intervention** from every consumer that pulled
the tagged image prior to the loss. Image consumers would get an error for
@ -64,10 +64,10 @@ could not validate the path to a trusted root: failed to validate data with curr
```
To correct this, they need to download a new image tag with that is signed with
the new key.
the new key.
## Related information
* [Content trust in Docker](/security/trust/content_trust)
* [Content trust in Docker](/security/trust/content_trust)
* [Automation with content trust](/security/trust/trust_automation)
* [Play in a content trust sandbox](/security/trust/trust_sandbox)

68
docs/security/trust/trust_sandbox.md
View file

@ -12,7 +12,7 @@ parent= "smn_content_trust"
This page explains how to set up and use a sandbox for experimenting with trust.
The sandbox allows you to configure and try trust operations locally without
impacting your production images.
impacting your production images.
Before working through this sandbox, you should have read through the [trust
overview](/security/trust/content_trust).
@ -48,7 +48,7 @@ The sandbox uses the Docker daemon on your local system. Within the `notarysandb
you interact with a local registry rather than the Docker Hub. This means
your everyday image repositories are not used. They are protected while you play.
When you play in the sandbox, you'll also create root and tagging keys. The
When you play in the sandbox, you'll also create root and repository keys. The
sandbox is configured to store all the keys and files inside the `notarysandbox`
container. Since the keys you create in the sandbox are for play only,
destroying the container destroys them as well.
@ -68,9 +68,9 @@ client inside the `notarysandbox` container connects to them over your network.
So, you'll need an entry for both the servers in your local `/etc/hosts` file.
1. Add an entry for the `notaryserver` to `/etc/hosts`.
$ sudo sh -c 'echo "127.0.0.1 notaryserver" >> /etc/hosts'
2. Add an entry for the `sandboxregistry` to `/etc/hosts`.
$ sudo sh -c 'echo "127.0.0.1 sandboxregistry" >> /etc/hosts'
@ -113,7 +113,7 @@ So, you'll need an entry for both the servers in your local `/etc/hosts` file.
RUN update-ca-certificates
ENTRYPOINT ["bash"]
6. Save and close the file.
7. Build the testing container.
@ -123,7 +123,7 @@ So, you'll need an entry for both the servers in your local `/etc/hosts` file.
Step 1 : FROM debian:jessie
...
Successfully built 5683f17e9d72
### Build and start up the trust servers
@ -137,7 +137,7 @@ Then, you'll use Docker Compose to build and start them on your local system.
2. Clone the `notary` project.
$ git clone -b trust-sandbox https://github.com/docker/notary.git
3. Clone the `distribution` project.
$ git clone https://github.com/docker/distribution.git
@ -152,31 +152,31 @@ Then, you'll use Docker Compose to build and start them on your local system.
5. Build the server images.
$ docker-compose build
$ docker-compose build
The first time you run this, the build takes some time.
6. Run the server containers on your local system.
$ docker-compose up -d
Once the trust services are up, you'll setup a local version of the Docker
Registry v2.
Registry v2.
7. Change to the `notarysandbox/distribution` directory.
8. Build the `sandboxregistry` server.
$ docker build -t sandboxregistry .
9. Start the `sandboxregistry` server running.
9. Start the `sandboxregistry` server running.
$ docker run -p 5000:5000 --name sandboxregistry sandboxregistry &
## Playing in the sandbox
Now that everything is setup, you can go into your `notarysandbox` container and
start testing Docker content trust.
start testing Docker content trust.
### Start the notarysandbox container
@ -187,7 +187,7 @@ communication among the containers.
```
$ docker run -it -v /var/run/docker.sock:/var/run/docker.sock --link notary_notaryserver_1:notaryserver --link sandboxregistry:sandboxregistry notarysandbox
root@0710762bb59a:/#
root@0710762bb59a:/#
```
Mounting the `docker.sock` gives the `notarysandbox` access to the `docker`
@ -196,28 +196,28 @@ container. When you destroy the container, you destroy the "play" keys.
### Test some trust operations
Now, you'll pull some images.
Now, you'll pull some images.
1. Download a `docker` image to test with.
# docker pull docker/trusttest
# docker pull docker/trusttest
docker pull docker/trusttest
Using default tag: latest
latest: Pulling from docker/trusttest
b3dbab3810fc: Pull complete
a9539b34a6ab: Pull complete
b3dbab3810fc: Pull complete
a9539b34a6ab: Pull complete
Digest: sha256:d149ab53f8718e987c3a3024bb8aa0e2caadf6c0328f1d9d850b2a2a67f2819a
Status: Downloaded newer image for docker/trusttest:latest
2. Tag it to be pushed to our sandbox registry:
2. Tag it to be pushed to our sandbox registry:
# docker tag docker/trusttest sandboxregistry:5000/test/trusttest:latest
3. Enable content trust.
# export DOCKER_CONTENT_TRUST=1
4. Identify the trust server.
# export DOCKER_CONTENT_TRUST_SERVER=https://notaryserver:4443
@ -237,8 +237,8 @@ Now, you'll pull some images.
# docker push sandboxregistry:5000/test/trusttest:latest
The push refers to a repository [sandboxregistry:5000/test/trusttest] (len: 1)
a9539b34a6ab: Image successfully pushed
b3dbab3810fc: Image successfully pushed
a9539b34a6ab: Image successfully pushed
b3dbab3810fc: Image successfully pushed
latest: digest: sha256:1d871dcb16805f0604f10d31260e79c22070b35abc71a3d1e7ee54f1042c8c7c size: 3348
Signing and pushing trust metadata
You are about to create a new root signing key passphrase. This passphrase
@ -247,22 +247,22 @@ Now, you'll pull some images.
key file itself secure and backed up. It is highly recommended that you use a
password manager to generate the passphrase and keep it safe. There will be no
way to recover this key. You can find the key in your config directory.
Enter passphrase for new offline key with id 8c69e04:
Repeat passphrase for new offline key with id 8c69e04:
Enter passphrase for new tagging key with id sandboxregistry:5000/test/trusttest (93c362a):
Repeat passphrase for new tagging key with id sandboxregistry:5000/test/trusttest (93c362a):
Enter passphrase for new root key with id 8c69e04:
Repeat passphrase for new root key with id 8c69e04:
Enter passphrase for new repository key with id sandboxregistry:5000/test/trusttest (93c362a):
Repeat passphrase for new repository key with id sandboxregistry:5000/test/trusttest (93c362a):
Finished initializing "sandboxregistry:5000/test/trusttest"
latest: digest: sha256:d149ab53f8718e987c3a3024bb8aa0e2caadf6c0328f1d9d850b2a2a67f2819a size: 3355
Signing and pushing trust metadata
7. Try pulling the image you just pushed:
# docker pull sandboxregistry:5000/test/trusttest
# docker pull sandboxregistry:5000/test/trusttest
Using default tag: latest
Pull (1 of 1): sandboxregistry:5000/test/trusttest:latest@sha256:1d871dcb16805f0604f10d31260e79c22070b35abc71a3d1e7ee54f1042c8c7c
sha256:1d871dcb16805f0604f10d31260e79c22070b35abc71a3d1e7ee54f1042c8c7c: Pulling from test/trusttest
b3dbab3810fc: Already exists
a9539b34a6ab: Already exists
b3dbab3810fc: Already exists
a9539b34a6ab: Already exists
Digest: sha256:1d871dcb16805f0604f10d31260e79c22070b35abc71a3d1e7ee54f1042c8c7c
Status: Downloaded newer image for sandboxregistry:5000/test/trusttest@sha256:1d871dcb16805f0604f10d31260e79c22070b35abc71a3d1e7ee54f1042c8c7c
Tagging sandboxregistry:5000/test/trusttest@sha256:1d871dcb16805f0604f10d31260e79c22070b35abc71a3d1e7ee54f1042c8c7c as sandboxregistry:5000/test/trusttest:latest
@ -281,7 +281,7 @@ data. Then, you try and pull it.
$ docker exec -it sandboxregistry bash
296db6068327#
3. Change into the registry storage.
3. Change into the registry storage.
You'll need to provide the `sha` you received when you pushed the image.
@ -314,8 +314,8 @@ data. Then, you try and pull it.
# docker pull sandboxregistry:5000/test/trusttest
Using default tag: latest
...
b3dbab3810fc: Verifying Checksum
a9539b34a6ab: Pulling fs layer
b3dbab3810fc: Verifying Checksum
a9539b34a6ab: Pulling fs layer
filesystem layer verification failed for digest sha256:aac0c133338db2b18ff054943cee3267fe50c75cdee969aed88b1992539ed042
You'll see the the pull did not complete because the trust system was

4
integration-cli/trust_server.go
View file

@ -125,11 +125,11 @@ func (s *DockerTrustSuite) trustedCmdWithServer(cmd *exec.Cmd, server string) {
}
func (s *DockerTrustSuite) trustedCmdWithPassphrases(cmd *exec.Cmd, rootPwd, repositoryPwd string) {
trustCmdEnv(cmd, s.not.address(), rootPwd, repositoryPwd)
trustCmdEnv(cmd, notaryURL, rootPwd, repositoryPwd)
}
func (s *DockerTrustSuite) trustedCmdWithDeprecatedEnvPassphrases(cmd *exec.Cmd, offlinePwd, taggingPwd string) {
trustCmdDeprecatedEnv(cmd, s.not.address(), offlinePwd, taggingPwd)
trustCmdDeprecatedEnv(cmd, notaryURL, offlinePwd, taggingPwd)
}
func trustCmdEnv(cmd *exec.Cmd, server, rootPwd, repositoryPwd string) {