linuxkit/docs/signing.md

Signing LinuxKit Hub Images

We sign and verify LinuxKit component images, such as linuxkit/kernel, using 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:

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:

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/<maintainer_name> 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:

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:

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:

notary -d ~/.docker/trust key import alice.key -r user