diff --git a/docs/signing/notary.md b/docs/signing/notary.md new file mode 100644 index 000000000..beaeb7f26 --- /dev/null +++ b/docs/signing/notary.md @@ -0,0 +1,49 @@ +# Signing LinuxKit Hub Images + +We sign and verify LinuxKit component images, such as `linuxkit/kernel`, using [Notary](https://github.com/docker/notary). + +This document details the process for setting this up, intended for maintainers. + +## Initialize a New Repository + +Let's say we're publishing a new `linuxkit/foo` image that we want to sign and verify in LinuxKit. +We first need to initialize the Notary repository: + +```apple js +notary -s https://notary.docker.io -d ~/.docker/trust init -p docker.io/linuxkit/foo +``` + +This command will generate some private keys in `~/.docker/trust` and ask you for passphrases such that they are encrypted at rest. +All linuxkit repositories are currently using the same root key so we can pin trust on key ID `1908a0cf4f55710138e63f65ab2a97e8fa3948e5ca3b8857a29f235a3b61ea1b`. + +We'll also let the notary server take control of the snapshot key, for easier delegation collaboration: +```apple js +notary -s https://notary.docker.io -d ~/.docker/trust key rotate docker.io/linuxkit/foo snapshot -r +``` + +## Add maintainers to delegation roles: + +Maintainers are to sign with `delegation` keys, which are adminstered by a non-root key. +Thusly, they are easily rotated without having to bring the root key online. +Additionally, maintainers can be added to separate roles for auditing purposes: the current setup is to add maintainers to both the `targets/releases` role that is intended +for release consumption, as well as an individual `targets/` role for auditing. +Docker will automatically sign into both roles when pushing with Docker Content Trust. + +Here's what the command looks like to add all maintainers to the `targets/releases` role: +```apple js +notary -s https://notary.docker.io -d ~/.docker/trust delegation add -p docker.io/linuxkit/foo targets/releases alice.crt bob.crt charlie.crt --all-paths +``` + +Here's what the commands look like to add all maintainers to their individually named roles: +```apple js +notary -s https://notary.docker.io -d ~/.docker/trust delegation add -p docker.io/linuxkit/foo targets/alice alice.crt --all-paths +notary -s https://notary.docker.io -d ~/.docker/trust delegation add -p docker.io/linuxkit/foo targets/bob bob.crt --all-paths +notary -s https://notary.docker.io -d ~/.docker/trust delegation add -p docker.io/linuxkit/foo targets/charlie charlie.crt --all-paths +``` + +## Maintainers import their private keys + +It's important that each maintainer imports their private key into Docker's key storage, so Docker can use it to sign: +```apple js +notary -d ~/.docker/trust key import alice.key -r user +``` diff --git a/pkg/ca-certificates/Makefile b/pkg/ca-certificates/Makefile index 8b019ad90..4c1c33359 100644 --- a/pkg/ca-certificates/Makefile +++ b/pkg/ca-certificates/Makefile @@ -11,4 +11,5 @@ tag: Dockerfile docker build --network=none -t $(ORG)/$(IMAGE):$(HASH) . push: tag - docker pull $(ORG)/$(IMAGE):$(HASH) || docker push $(ORG)/$(IMAGE):$(HASH) + DOCKER_CONTENT_TRUST=1 docker pull $(ORG)/$(IMAGE):$(HASH) || \ + DOCKER_CONTENT_TRUST=1 docker push $(ORG)/$(IMAGE):$(HASH) diff --git a/pkg/containerd/Makefile b/pkg/containerd/Makefile index 5dd0274c0..8ef90ce89 100644 --- a/pkg/containerd/Makefile +++ b/pkg/containerd/Makefile @@ -11,4 +11,5 @@ tag: Dockerfile docker build -t $(ORG)/$(IMAGE):$(HASH) . push: tag - docker pull $(ORG)/$(IMAGE):$(HASH) || docker push $(ORG)/$(IMAGE):$(HASH) + DOCKER_CONTENT_TRUST=1 docker pull $(ORG)/$(IMAGE):$(HASH) || \ + DOCKER_CONTENT_TRUST=1 docker push $(ORG)/$(IMAGE):$(HASH) diff --git a/pkg/dhcpcd/Makefile b/pkg/dhcpcd/Makefile index 4c55bf351..1daa183bf 100644 --- a/pkg/dhcpcd/Makefile +++ b/pkg/dhcpcd/Makefile @@ -11,5 +11,5 @@ tag: $(DEPS) docker build --squash --no-cache --network=none -t $(ORG)/$(IMAGE):$(HASH) . push: tag - docker pull $(ORG)/$(IMAGE):$(HASH) || \ - docker push $(ORG)/$(IMAGE):$(HASH) + DOCKER_CONTENT_TRUST=1 docker pull $(ORG)/$(IMAGE):$(HASH) || \ + DOCKER_CONTENT_TRUST=1 docker push $(ORG)/$(IMAGE):$(HASH) diff --git a/pkg/format/Makefile b/pkg/format/Makefile index f43012840..24ede284f 100644 --- a/pkg/format/Makefile +++ b/pkg/format/Makefile @@ -11,5 +11,5 @@ tag: $(DEPS) docker build --squash --no-cache --network=none -t $(ORG)/$(IMAGE):$(HASH) . push: tag - docker pull $(ORG)/$(IMAGE):$(HASH) || \ - docker push $(ORG)/$(IMAGE):$(HASH) + DOCKER_CONTENT_TRUST=1 docker pull $(ORG)/$(IMAGE):$(HASH) || \ + DOCKER_CONTENT_TRUST=1 docker push $(ORG)/$(IMAGE):$(HASH) diff --git a/pkg/init/Makefile b/pkg/init/Makefile index 135e8b2e2..4b5eaf067 100644 --- a/pkg/init/Makefile +++ b/pkg/init/Makefile @@ -11,5 +11,5 @@ tag: $(DEPS) docker build --no-cache --network=none -t $(ORG)/$(IMAGE):$(HASH) . push: tag - docker pull $(ORG)/$(IMAGE):$(HASH) || \ - docker push $(ORG)/$(IMAGE):$(HASH) + DOCKER_CONTENT_TRUST=1 docker pull $(ORG)/$(IMAGE):$(HASH) || \ + DOCKER_CONTENT_TRUST=1 docker push $(ORG)/$(IMAGE):$(HASH) diff --git a/pkg/metadata/Makefile b/pkg/metadata/Makefile index 1d42a8d53..c1936a135 100644 --- a/pkg/metadata/Makefile +++ b/pkg/metadata/Makefile @@ -27,9 +27,9 @@ hash: Dockerfile $(DEPS) find $^ -type f | xargs cat | docker run --rm -i $(SHA_IMAGE) sha1sum - | sed 's/ .*//' > hash push: hash container - docker pull $(ORG)/$(IMAGE):$(shell cat hash) || \ + DOCKER_CONTENT_TRUST=1 docker pull $(ORG)/$(IMAGE):$(shell cat hash) || \ (docker tag $(IMAGE):build $(ORG)/$(IMAGE):$(shell cat hash) && \ - docker push $(ORG)/$(IMAGE):$(shell cat hash)) + DOCKER_CONTENT_TRUST=1 docker push $(ORG)/$(IMAGE):$(shell cat hash)) docker rmi $(IMAGE):build rm -f hash diff --git a/pkg/mount/Makefile b/pkg/mount/Makefile index 1f37b206f..bb4571c82 100644 --- a/pkg/mount/Makefile +++ b/pkg/mount/Makefile @@ -11,5 +11,5 @@ tag: $(DEPS) docker build --squash --no-cache --network=none -t $(ORG)/$(IMAGE):$(HASH) . push: tag - docker pull $(ORG)/$(IMAGE):$(HASH) || \ - docker push $(ORG)/$(IMAGE):$(HASH) + DOCKER_CONTENT_TRUST=1 docker pull $(ORG)/$(IMAGE):$(HASH) || \ + DOCKER_CONTENT_TRUST=1 docker push $(ORG)/$(IMAGE):$(HASH) diff --git a/pkg/openntpd/Makefile b/pkg/openntpd/Makefile index 0912f8f5f..2ed1be291 100644 --- a/pkg/openntpd/Makefile +++ b/pkg/openntpd/Makefile @@ -11,5 +11,5 @@ tag: $(DEPS) docker build --squash --no-cache --network=none -t $(ORG)/$(IMAGE):$(HASH) . push: tag - docker pull $(ORG)/$(IMAGE):$(HASH) || \ - docker push $(ORG)/$(IMAGE):$(HASH) + DOCKER_CONTENT_TRUST=1 docker pull $(ORG)/$(IMAGE):$(HASH) || \ + DOCKER_CONTENT_TRUST=1 docker push $(ORG)/$(IMAGE):$(HASH) diff --git a/pkg/runc/Makefile b/pkg/runc/Makefile index 1a56b0c9c..18a37fbe7 100644 --- a/pkg/runc/Makefile +++ b/pkg/runc/Makefile @@ -11,4 +11,5 @@ tag: Dockerfile docker build -t $(ORG)/$(IMAGE):$(HASH) . push: tag - docker pull $(ORG)/$(IMAGE):$(HASH) || docker push $(ORG)/$(IMAGE):$(HASH) + DOCKER_CONTENT_TRUST=1 docker pull $(ORG)/$(IMAGE):$(HASH) || \ + DOCKER_CONTENT_TRUST=1 docker push $(ORG)/$(IMAGE):$(HASH) diff --git a/pkg/sshd/Makefile b/pkg/sshd/Makefile index 60d62ef2d..01b08e8fa 100644 --- a/pkg/sshd/Makefile +++ b/pkg/sshd/Makefile @@ -11,5 +11,5 @@ tag: $(DEPS) docker build --squash --no-cache --network=none -t $(ORG)/$(IMAGE):$(HASH) . push: tag - docker pull $(ORG)/$(IMAGE):$(HASH) || \ - docker push $(ORG)/$(IMAGE):$(HASH) + DOCKER_CONTENT_TRUST=1 docker pull $(ORG)/$(IMAGE):$(HASH) || \ + DOCKER_CONTENT_TRUST=1 docker push $(ORG)/$(IMAGE):$(HASH) diff --git a/pkg/sysctl/Makefile b/pkg/sysctl/Makefile index de7ae2bba..c23d22151 100644 --- a/pkg/sysctl/Makefile +++ b/pkg/sysctl/Makefile @@ -11,5 +11,5 @@ tag: $(DEPS) docker build --squash --no-cache --network=none -t $(ORG)/$(IMAGE):$(HASH) . push: tag - docker pull $(ORG)/$(IMAGE):$(HASH) || \ - docker push $(ORG)/$(IMAGE):$(HASH) + DOCKER_CONTENT_TRUST=1 docker pull $(ORG)/$(IMAGE):$(HASH) || \ + DOCKER_CONTENT_TRUST=1 docker push $(ORG)/$(IMAGE):$(HASH) diff --git a/pkg/sysfs/Makefile b/pkg/sysfs/Makefile index cebfb5003..4ac3947fc 100644 --- a/pkg/sysfs/Makefile +++ b/pkg/sysfs/Makefile @@ -11,5 +11,5 @@ tag: $(DEPS) docker build --squash --no-cache --network=none -t $(ORG)/$(IMAGE):$(HASH) . push: tag - docker pull $(ORG)/$(IMAGE):$(HASH) || \ - docker push $(ORG)/$(IMAGE):$(HASH) + DOCKER_CONTENT_TRUST=1 docker pull $(ORG)/$(IMAGE):$(HASH) || \ + DOCKER_CONTENT_TRUST=1 docker push $(ORG)/$(IMAGE):$(HASH) diff --git a/tools/alpine/Makefile b/tools/alpine/Makefile index d5447d99b..d62bb98a2 100644 --- a/tools/alpine/Makefile +++ b/tools/alpine/Makefile @@ -12,9 +12,9 @@ hash: docker run --rm $(IMAGE):build sh -c 'echo /lib/apk/db/installed $$(find /mirror -name '*.apk' -type f) $$(find /go/bin -type f) | xargs cat | sha1sum' | sed 's/ .*//' > $@ push: hash - docker pull $(ORG)/$(IMAGE):$(shell cat hash) || \ + DOCKER_CONTENT_TRUST=1 docker pull $(ORG)/$(IMAGE):$(shell cat hash) || \ (docker tag $(IMAGE):build $(ORG)/$(IMAGE):$(shell cat hash) && \ - docker push $(ORG)/$(IMAGE):$(shell cat hash)) + DOCKER_CONTENT_TRUST=1 docker push $(ORG)/$(IMAGE):$(shell cat hash)) docker run --rm $(IMAGE):build find /mirror -name '*.apk' -exec basename '{}' .apk \; | sort | (echo '# automatically generated list of installed packages'; cat -) > versions docker rmi $(IMAGE):build rm -f hash