Document signing images

[dfreilich]

Summary

There has been some requests for signing images. While it is still an open discussion (see buildpacks/pack#268 and buildpacks/lifecycle#180), it is currently possible to sign images, once created, using notary v1. Add a walkthrough to sign an issue built through pack.

What questions should this documentation answer?

• What is a signed image?
• How can I sign an image?
• Is this through pack, or a separate tool?

Who is the target audience for this documentation?

• App Developer
• Operator
• Security folk

Additional Information

xpost from private issue, researched by @djoyahoy:

---

Here are the steps to integrate with notary outside the docker CLI:

Setup

1. docker pull alpine
2. start a local docker registry with docker run -p 5000:5000 --restart=always --name registry registry:2
3. git clone the notary project from github and go install the notary binary
4. start a local notary server with cd notary && docker-compose up
5. export DOCKER_CONTENT_TRUST_SERVER=https://localhost:4443

Note : Run all notary commands from the notary directory to access the root-ca.crt

Testing Notary with the Docker CLI

1. docker trust key generate test
2. docker trust signer add --key test.pub test localhost:5000/foo
3. notary -s https://localhost:4443 -d ~/.docker/trust/ --tlscacert ./fixtures/root-ca.crt delegation list localhost:5000/foo
4. docker tag alpine localhost:5000/foo:alpine
5. docker trust sign localhost:5000/foo:alpine
6. notary -s https://localhost:4443 -d ~/.docker/trust/ --tlscacert ./fixtures/root-ca.crt list localhost:5000/foo
7. docker trust inspect --pretty localhost:5000/foo:alpine
8. docker rmi localhost:5000/foo:alpine
9. DOCKER_CONTENT_TRUST=1 docker pull localhost:5000/foo:alpine
10. docker trust revoke localhost:5000/foo:alpine
11. docker rmi localhost:5000/foo:alpine
12. DOCKER_CONTENT_TRUST=1 docker pull localhost:5000/foo:alpine

Testing Notary with the Notary CLI

Note: The first command is a docker CLI command because this is how our users would most likely add their keys to Notary. However, if they are well versed with Notary, they can add the keys with the Notary CLI as well.

1. docker trust signer add --key test.pub test localhost:5000/bar
2. docker tag alpine localhost:5000/bar:alpine
3. docker push localhost:5000/bar:alpine
4. Copy the image digest and number of bytes.
5. notary -s https://localhost:4443 --tlscacert ./fixtures/root-ca.crt -d ~/.docker/trust addhash -p localhost:5000/bar alpine <bytes> --sha256 <digest> -r targets/test
6. notary -s https://localhost:4443 --tlscacert ./fixtures/root-ca.crt -d ~/.docker/trust/ list localhost:5000/bar -r targets/test
7. docker rmi localhost:5000/bar:alpine
8. DOCKER_CONTENT_TRUST=1 docker pull localhost:5000/bar:alpine
9. notary -s https://localhost:4443 --tlscacert ./fixtures/root-ca.crt -d ~/.docker/trust/ remove -p localhost:5000/bar alpine -r targets/test
10. docker rmi localhost:5000/bar:alpine
11. DOCKER_CONTENT_TRUST=1 docker pull localhost:5000/bar:alpine

[jromero]

This seems like it's a little out of scope for our project. At least until we have more integrated support for signing. IMO, this is still valuable but probably better served as a blog post.

cc: @jkutner