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 +```