Skip to content

Commit 5d7168c

Browse files
craig-osterhoutcraig-osterhout
authored
engine: format using code fence (#23385)
<!--Delete sections as needed --> ## Description Formatted codeblocks with code fence to prevent styling issue. Cleaned up some spacing. https://deploy-preview-23385--docsdocker.netlify.app/engine/security/trust/trust_sandbox/ ## Related issues or tickets Closes #23376 ## Reviews <!-- Notes for reviewers here --> <!-- List applicable reviews (optionally @tag reviewers) --> - [ ] Editorial review --------- Signed-off-by: Craig <[email protected]>
1 parent 0a34ff4 commit 5d7168c

File tree

1 file changed

+163
-129
lines changed

1 file changed

+163
-129
lines changed

‎content/manuals/engine/security/trust/trust_sandbox.md‎

Lines changed: 163 additions & 129 deletions
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,7 @@ sandbox is configured to store all the keys and files inside the `trustsandbox`
5151
container. Since the keys you create in the sandbox are for play only,
5252
destroying the container destroys them as well.
5353

54-
By using a docker-in-docker image for the `trustsandbox` container, you also
54+
By using a `docker-in-docker` image for the `trustsandbox` container, you also
5555
don't pollute your real Docker daemon cache with any images you push and pull.
5656
The images are stored in an anonymous volume attached to this container,
5757
and can be destroyed after you destroy the container.
@@ -64,61 +64,68 @@ the `trustsandbox` container, the Notary server, and the Registry server.
6464

6565
1. Create a new `trustsandbox` directory and change into it.
6666

67-
$ mkdir trustsandbox
68-
$ cd trustsandbox
67+
```console
68+
$ mkdir trustsandbox
69+
$ cd trustsandbox
70+
```
6971

7072
2. Create a file called `compose.yaml` with your favorite editor. For example, using vim:
7173

72-
$ touch compose.yaml
73-
$ vim compose.yaml
74+
```console
75+
$ touch compose.yaml
76+
$ vim compose.yaml
77+
```
7478

7579
3. Add the following to the new file.
7680

77-
version: "2"
78-
services:
79-
notaryserver:
80-
image: dockersecurity/notary_autobuilds:server-v0.5.1
81-
volumes:
82-
- notarycerts:/var/lib/notary/fixtures
83-
networks:
84-
- sandbox
85-
environment:
86-
- NOTARY_SERVER_STORAGE_TYPE=memory
87-
- NOTARY_SERVER_TRUST_SERVICE_TYPE=local
88-
sandboxregistry:
89-
image: registry:2.4.1
90-
networks:
91-
- sandbox
92-
container_name: sandboxregistry
93-
trustsandbox:
94-
image: docker:dind
95-
networks:
96-
- sandbox
97-
volumes:
98-
- notarycerts:/notarycerts
99-
privileged: true
100-
container_name: trustsandbox
101-
entrypoint: ""
102-
command: |-
103-
sh -c '
104-
cp /notarycerts/root-ca.crt /usr/local/share/ca-certificates/root-ca.crt &&
105-
update-ca-certificates &&
106-
dockerd-entrypoint.sh --insecure-registry sandboxregistry:5000'
107-
volumes:
108-
notarycerts:
109-
external: false
110-
networks:
111-
sandbox:
112-
external: false
113-
81+
```yaml
82+
version: "2"
83+
services:
84+
notaryserver:
85+
image: dockersecurity/notary_autobuilds:server-v0.5.1
86+
volumes:
87+
- notarycerts:/var/lib/notary/fixtures
88+
networks:
89+
- sandbox
90+
environment:
91+
- NOTARY_SERVER_STORAGE_TYPE=memory
92+
- NOTARY_SERVER_TRUST_SERVICE_TYPE=local
93+
sandboxregistry:
94+
image: registry:2.4.1
95+
networks:
96+
- sandbox
97+
container_name: sandboxregistry
98+
trustsandbox:
99+
image: docker:dind
100+
networks:
101+
- sandbox
102+
volumes:
103+
- notarycerts:/notarycerts
104+
privileged: true
105+
container_name: trustsandbox
106+
entrypoint: ""
107+
command: |-
108+
sh -c '
109+
cp /notarycerts/root-ca.crt /usr/local/share/ca-certificates/root-ca.crt &&
110+
update-ca-certificates &&
111+
dockerd-entrypoint.sh --insecure-registry sandboxregistry:5000'
112+
volumes:
113+
notarycerts:
114+
external: false
115+
networks:
116+
sandbox:
117+
external: false
118+
```
114119
4. Save and close the file.
115120
116121
5. Run the containers on your local system.
117122
118-
$ docker compose up -d
123+
```console
124+
$ docker compose up -d
125+
```
119126

120-
The first time you run this, the docker-in-docker, Notary server, and registry
121-
images are downloaded from Docker Hub.
127+
The first time you run this, the `docker-in-docker`, Notary server, and registry
128+
images are downloaded from Docker Hub.
122129

123130

124131
## Play in the sandbox
@@ -127,68 +134,79 @@ Now that everything is setup, you can go into your `trustsandbox` container and
127134
start testing Docker content trust. From your host machine, obtain a shell
128135
in the `trustsandbox` container.
129136

130-
$ docker container exec -it trustsandbox sh
131-
/ #
137+
```console
138+
$ docker container exec -it trustsandbox sh
139+
/ #
140+
```
132141

133142
### Test some trust operations
134143

135144
Now, pull some images from within the `trustsandbox` container.
136145

137146
1. Download a `docker` image to test with.
138147

139-
/ # docker pull docker/trusttest
140-
docker pull docker/trusttest
141-
Using default tag: latest
142-
latest: Pulling from docker/trusttest
143-
144-
b3dbab3810fc: Pull complete
145-
a9539b34a6ab: Pull complete
146-
Digest: sha256:d149ab53f8718e987c3a3024bb8aa0e2caadf6c0328f1d9d850b2a2a67f2819a
147-
Status: Downloaded newer image for docker/trusttest:latest
148+
```console
149+
/ # docker pull docker/trusttest
150+
docker pull docker/trusttest
151+
Using default tag: latest
152+
latest: Pulling from docker/trusttest
153+
b3dbab3810fc: Pull complete
154+
a9539b34a6ab: Pull complete
155+
Digest: sha256:d149ab53f8718e987c3a3024bb8aa0e2caadf6c0328f1d9d850b2a2a67f2819a
156+
Status: Downloaded newer image for docker/trusttest:latest
157+
```
148158

149-
2. Tag it to be pushed to our sandbox registry:
159+
2. Tag it to be pushed to your sandbox registry:
150160

151-
/ # docker tag docker/trusttest sandboxregistry:5000/test/trusttest:latest
161+
```console
162+
/ # docker tag docker/trusttest sandboxregistry:5000/test/trusttest:latest
163+
```
152164

153165
3. Enable content trust.
154166

155-
/ # export DOCKER_CONTENT_TRUST=1
167+
```console
168+
/ # export DOCKER_CONTENT_TRUST=1
169+
```
156170

157171
4. Identify the trust server.
158172

159-
/ # export DOCKER_CONTENT_TRUST_SERVER=https://notaryserver:4443
173+
```console
174+
/ # export DOCKER_CONTENT_TRUST_SERVER=https://notaryserver:4443
175+
```
160176

161177
This step is only necessary because the sandbox is using its own server.
162178
Normally, if you are using the Docker Public Hub this step isn't necessary.
163179

164180
5. Pull the test image.
165181

166-
/ # docker pull sandboxregistry:5000/test/trusttest
167-
Using default tag: latest
168-
Error: remote trust data does not exist for sandboxregistry:5000/test/trusttest: notaryserver:4443 does not have trust data for sandboxregistry:5000/test/trusttest
169-
182+
```console
183+
/ # docker pull sandboxregistry:5000/test/trusttest
184+
Using default tag: latest
185+
Error: remote trust data does not exist for sandboxregistry:5000/test/trusttest: notaryserver:4443 does not have trust data for sandboxregistry:5000/test/trusttest
186+
```
170187
You see an error, because this content doesn't exist on the `notaryserver` yet.
171188

172189
6. Push and sign the trusted image.
173-
174-
/ # docker push sandboxregistry:5000/test/trusttest:latest
175-
The push refers to a repository [sandboxregistry:5000/test/trusttest]
176-
5f70bf18a086: Pushed
177-
c22f7bc058a9: Pushed
178-
latest: digest: sha256:ebf59c538accdf160ef435f1a19938ab8c0d6bd96aef8d4ddd1b379edf15a926 size: 734
179-
Signing and pushing trust metadata
180-
You are about to create a new root signing key passphrase. This passphrase
181-
will be used to protect the most sensitive key in your signing system. Please
182-
choose a long, complex passphrase and be careful to keep the password and the
183-
key file itself secure and backed up. It is highly recommended that you use a
184-
password manager to generate the passphrase and keep it safe. There will be no
185-
way to recover this key. You can find the key in your config directory.
186-
Enter passphrase for new root key with ID 27ec255:
187-
Repeat passphrase for new root key with ID 27ec255:
188-
Enter passphrase for new repository key with ID 58233f9 (sandboxregistry:5000/test/trusttest):
189-
Repeat passphrase for new repository key with ID 58233f9 (sandboxregistry:5000/test/trusttest):
190-
Finished initializing "sandboxregistry:5000/test/trusttest"
191-
Successfully signed "sandboxregistry:5000/test/trusttest":latest
190+
```console
191+
/ # docker push sandboxregistry:5000/test/trusttest:latest
192+
The push refers to a repository [sandboxregistry:5000/test/trusttest]
193+
5f70bf18a086: Pushed
194+
c22f7bc058a9: Pushed
195+
latest: digest: sha256:ebf59c538accdf160ef435f1a19938ab8c0d6bd96aef8d4ddd1b379edf15a926 size: 734
196+
Signing and pushing trust metadata
197+
You are about to create a new root signing key passphrase. This passphrase
198+
will be used to protect the most sensitive key in your signing system. Please
199+
choose a long, complex passphrase and be careful to keep the password and the
200+
key file itself secure and backed up. It is highly recommended that you use a
201+
password manager to generate the passphrase and keep it safe. There will be no
202+
way to recover this key. You can find the key in your config directory.
203+
Enter passphrase for new root key with ID 27ec255:
204+
Repeat passphrase for new root key with ID 27ec255:
205+
Enter passphrase for new repository key with ID 58233f9 (sandboxregistry:5000/test/trusttest):
206+
Repeat passphrase for new repository key with ID 58233f9 (sandboxregistry:5000/test/trusttest):
207+
Finished initializing "sandboxregistry:5000/test/trusttest"
208+
Successfully signed "sandboxregistry:5000/test/trusttest":latest
209+
```
192210

193211
Because you are pushing this repository for the first time, Docker creates
194212
new root and repository keys and asks you for passphrases with which to
@@ -197,13 +215,15 @@ Now, pull some images from within the `trustsandbox` container.
197215

198216
7. Try pulling the image you just pushed:
199217

200-
/ # docker pull sandboxregistry:5000/test/trusttest
201-
Using default tag: latest
202-
Pull (1 of 1): sandboxregistry:5000/test/trusttest:latest@sha256:ebf59c538accdf160ef435f1a19938ab8c0d6bd96aef8d4ddd1b379edf15a926
203-
sha256:ebf59c538accdf160ef435f1a19938ab8c0d6bd96aef8d4ddd1b379edf15a926: Pulling from test/trusttest
204-
Digest: sha256:ebf59c538accdf160ef435f1a19938ab8c0d6bd96aef8d4ddd1b379edf15a926
205-
Status: Downloaded newer image for sandboxregistry:5000/test/trusttest@sha256:ebf59c538accdf160ef435f1a19938ab8c0d6bd96aef8d4ddd1b379edf15a926
206-
Tagging sandboxregistry:5000/test/trusttest@sha256:ebf59c538accdf160ef435f1a19938ab8c0d6bd96aef8d4ddd1b379edf15a926 as sandboxregistry:5000/test/trusttest:latest
218+
```console
219+
/ # docker pull sandboxregistry:5000/test/trusttest
220+
Using default tag: latest
221+
Pull (1 of 1): sandboxregistry:5000/test/trusttest:latest@sha256:ebf59c538accdf160ef435f1a19938ab8c0d6bd96aef8d4ddd1b379edf15a926
222+
sha256:ebf59c538accdf160ef435f1a19938ab8c0d6bd96aef8d4ddd1b379edf15a926: Pulling from test/trusttest
223+
Digest: sha256:ebf59c538accdf160ef435f1a19938ab8c0d6bd96aef8d4ddd1b379edf15a926
224+
Status: Downloaded newer image for sandboxregistry:5000/test/trusttest@sha256:ebf59c538accdf160ef435f1a19938ab8c0d6bd96aef8d4ddd1b379edf15a926
225+
Tagging sandboxregistry:5000/test/trusttest@sha256:ebf59c538accdf160ef435f1a19938ab8c0d6bd96aef8d4ddd1b379edf15a926 as sandboxregistry:5000 test/trusttest:latest
226+
```
207227

208228

209229
### Test with malicious images
@@ -212,15 +232,17 @@ What happens when data is corrupted and you try to pull it when trust is
212232
enabled? In this section, you go into the `sandboxregistry` and tamper with some
213233
data. Then, you try and pull it.
214234

215-
1. Leave the `trustsandbox` shell and container running.
235+
1. Leave the `trustsandbox` shell and container running.
216236

217-
2. Open a new interactive terminal from your host, and obtain a shell into the
218-
`sandboxregistry` container.
237+
2. Open a new interactive terminal from your host, and obtain a shell into the
238+
`sandboxregistry` container.
219239

220-
$ docker container exec -it sandboxregistry bash
221-
root@65084fc6f047:/#
240+
```console
241+
$ docker container exec -it sandboxregistry bash
242+
root@65084fc6f047:/#
243+
```
222244

223-
3. List the layers for the `test/trusttest` image you pushed:
245+
3. List the layers for the `test/trusttest` image you pushed:
224246

225247
```console
226248
root@65084fc6f047:/# ls -l /var/lib/registry/docker/registry/v2/repositories/test/trusttest/_layers/sha256
@@ -230,51 +252,61 @@ data. Then, you try and pull it.
230252
drwxr-xr-x 2 root root 4096 Jun 10 17:26 cc7629d1331a7362b5e5126beb5bf15ca0bf67eb41eab994c719a45de53255cd
231253
```
232254

233-
4. Change into the registry storage for one of those layers (this is in a different directory):
255+
4. Change into the registry storage for one of those layers (this is in a different directory):
234256

235-
root@65084fc6f047:/# cd /var/lib/registry/docker/registry/v2/blobs/sha256/aa/aac0c133338db2b18ff054943cee3267fe50c75cdee969aed88b1992539ed042
257+
```console
258+
root@65084fc6f047:/# cd /var/lib/registry/docker/registry/v2/blobs/sha256/aa/aac0c133338db2b18ff054943cee3267fe50c75cdee969aed88b1992539ed042
259+
```
236260

237-
5. Add malicious data to one of the `trusttest` layers:
261+
5. Add malicious data to one of the `trusttest` layers:
238262

239-
root@65084fc6f047:/# echo "Malicious data" > data
263+
```console
264+
root@65084fc6f047:/# echo "Malicious data" > data
265+
```
240266

241-
6. Go back to your `trustsandbox` terminal.
267+
6. Go back to your `trustsandbox` terminal.
242268

243-
7. List the `trusttest` image.
269+
7. List the `trusttest` image.
244270

245-
/ # docker image ls | grep trusttest
246-
REPOSITORY TAG IMAGE ID CREATED SIZE
247-
docker/trusttest latest cc7629d1331a 11 months ago 5.025 MB
248-
sandboxregistry:5000/test/trusttest latest cc7629d1331a 11 months ago 5.025 MB
249-
sandboxregistry:5000/test/trusttest <none> cc7629d1331a 11 months ago 5.025 MB
271+
```console
272+
/ # docker image ls | grep trusttest
273+
REPOSITORY TAG IMAGE ID CREATED SIZE
274+
docker/trusttest latest cc7629d1331a 11 months ago 5.025 MB
275+
sandboxregistry:5000/test/trusttest latest cc7629d1331a 11 months ago 5.025 MB
276+
sandboxregistry:5000/test/trusttest <none> cc7629d1331a 11 months ago 5.025 MB
277+
```
250278

251-
8. Remove the `trusttest:latest` image from our local cache.
279+
8. Remove the `trusttest:latest` image from your local cache.
252280

253-
/ # docker image rm -f cc7629d1331a
254-
Untagged: docker/trusttest:latest
255-
Untagged: sandboxregistry:5000/test/trusttest:latest
256-
Untagged: sandboxregistry:5000/test/trusttest@sha256:ebf59c538accdf160ef435f1a19938ab8c0d6bd96aef8d4ddd1b379edf15a926
257-
Deleted: sha256:cc7629d1331a7362b5e5126beb5bf15ca0bf67eb41eab994c719a45de53255cd
258-
Deleted: sha256:2a1f6535dc6816ffadcdbe20590045e6cbf048d63fd4cc753a684c9bc01abeea
259-
Deleted: sha256:c22f7bc058a9a8ffeb32989b5d3338787e73855bf224af7aa162823da015d44c
281+
```console
282+
/ # docker image rm -f cc7629d1331a
283+
Untagged: docker/trusttest:latest
284+
Untagged: sandboxregistry:5000/test/trusttest:latest
285+
Untagged: sandboxregistry:5000/test/trusttest@sha256:ebf59c538accdf160ef435f1a19938ab8c0d6bd96aef8d4ddd1b379edf15a926
286+
Deleted: sha256:cc7629d1331a7362b5e5126beb5bf15ca0bf67eb41eab994c719a45de53255cd
287+
Deleted: sha256:2a1f6535dc6816ffadcdbe20590045e6cbf048d63fd4cc753a684c9bc01abeea
288+
Deleted: sha256:c22f7bc058a9a8ffeb32989b5d3338787e73855bf224af7aa162823da015d44c
289+
```
260290

261-
Docker does not re-download images that it already has cached, but we want
262-
Docker to attempt to download the tampered image from the registry and reject
263-
it because it is invalid.
291+
Docker does not re-download images that it already has cached, but you want
292+
Docker to attempt to download the tampered image from the registry and reject
293+
it because it is invalid.
264294

265-
9. Pull the image again. This downloads the image from the registry, because we don't have it cached.
295+
9. Pull the image again. This downloads the image from the registry, because you don't have it cached.
266296

267-
/ # docker pull sandboxregistry:5000/test/trusttest
268-
Using default tag: latest
269-
Pull (1 of 1): sandboxregistry:5000/test/trusttest:latest@sha256:35d5bc26fd358da8320c137784fe590d8fcf9417263ef261653e8e1c7f15672e
270-
sha256:35d5bc26fd358da8320c137784fe590d8fcf9417263ef261653e8e1c7f15672e: Pulling from test/trusttest
297+
```console
298+
/ # docker pull sandboxregistry:5000/test/trusttest
299+
Using default tag: latest
300+
Pull (1 of 1): sandboxregistry:5000/test/trusttest:latest@sha256:35d5bc26fd358da8320c137784fe590d8fcf9417263ef261653e8e1c7f15672e
301+
sha256:35d5bc26fd358da8320c137784fe590d8fcf9417263ef261653e8e1c7f15672e: Pulling from test/trusttest
271302

272-
aac0c133338d: Retrying in 5 seconds
273-
a3ed95caeb02: Download complete
274-
error pulling image configuration: unexpected EOF
303+
aac0c133338d: Retrying in 5 seconds
304+
a3ed95caeb02: Download complete
305+
error pulling image configuration: unexpected EOF
306+
```
275307

276-
The pull did not complete because the trust system couldn't verify the
277-
image.
308+
The pull did not complete because the trust system couldn't verify the
309+
image.
278310

279311
## More play in the sandbox
280312

@@ -289,4 +321,6 @@ When you are done, and want to clean up all the services you've started and any
289321
anonymous volumes that have been created, just run the following command in the
290322
directory where you've created your Docker Compose file:
291323

292-
$ docker compose down -v
324+
```console
325+
$ docker compose down -v
326+
```

0 commit comments

Comments
 (0)