Chapter 4. Signing container images

Procedure

1. Generate a GPG key:

   # gpg --full-gen-key

2. Export the public key:

   # gpg --output <path>/key.gpg --armor --export <username>@redhat.com

3. Build the container image using Containerfile in the current directory:

   $ podman build -t <registry>/<namespace>/<image>

   Replace <registry>, <namespace>, and <image> with the container image identifiers. For more details, see Container registries.

4. Sign the image and push it to the registry:

    $  podman push \
       --sign-by <username>@redhat.com \
       <registry>/<namespace>/<image>

   Note

   If you need to sign existing images while moving them across container registries, you can use the skopeo copy command.

5. Optional. Display the new image signature:

   # (cd /var/lib/containers/sigstore/; find . -type f)
   ./<image>@sha256=<digest>/signature-1

6. Copy your local signatures to the lookaside web server:

   # rsync -a /var/lib/containers/sigstore user@registry-lookaside.example.com:/registry-lookaside/webroot/sigstore

Procedure

1. Update a trust scope for the <registry>:

   $ podman image trust set -f <path>/key.gpg <registry>/<namespace>

2. Optional. Verify the trust policy configuration by displaying the /etc/containers/policy.json file:

   $ cat /etc/containers/policy.json
   {
     ...
     "transports": {
       "docker": {
         "<registry>/<namespace>": [
           {
             "type": "signedBy",
             "keyType": "GPGKeys",
             "keyPath": "<path>/key.gpg"
           }
         ]
       }
     }
   }

   Note

   Typically, the /etc/containers.policy.json file is configured at a level of organization where the same keys are used. For example, <registry>/<namespace> for a public registry, or just a <registry> for a single-company dedicated registry.

3. Pull the image:

   # podman pull <registry>/<namespace>/<image>
   ...
   Storing signatures
   e7d92cdc71feacf90708cb59182d0df1b911f8ae022d29e8e95d75ca6a99776a

   The podman pull command enforces signature presence as configured, no extra options are required.

1. Install the cosign tool:

   $ git clone https://github.com/sigstore/cosign
   $ cd cosign
   $ make ./cosign

2. Generate a public and private key pair:

   $ ./cosign generate-key-pair
   ...
   Private key written to cosign.key
   Public key written to cosign.pub

Procedure

1. Add the following content to the /etc/containers/registries.d/default.yaml file:

   docker:
       <registry>:
           use-sigstore-attachments: true

   By setting the use-sigstore-attachments option, Podman and Skopeo can read and write the container sigstore signatures together with the image and save them in the same repository as the signed image.

   Note

   You can edit the system-wide registry configuration in the /etc/containers/registries.d/default.yaml file. You can also edit the registry or repository configuration section in any YAML file in the /etc/containers/registries.d directory. All YAML files are read and the filename can be arbitrary. A single scope (default-docker, registry, or namespace) can only exist in one file within the /etc/containers/registries.d directory.

2. Build the container image using Containerfile in the current directory:

   $ podman build -t <registry>/<namespace>/<image>

3. Sign the image and push it to the registry:

   $ podman push --sign-by-sigstore-private-key ./cosign.key <registry>/<namespace>/image>

   The podman push command pushes the <registry>/<namespace>/<image> local image to the remote registry as <registry>/<namespace>/<image>. The --sign-by-sigstore-private-key option adds a sigstore signature using the cosign.key private key to the <registry>/<namespace>/<image> image. The image and the sigstore signature are uploaded to the remote registry.

Procedure

1. Add the following content to the /etc/containers/registries.d/default.yaml file:

   docker:
       <registry>:
           use-sigstore-attachments: true

   By setting the use-sigstore-attachments option, Podman and Skopeo can read and write the container sigstore signatures together with the image and save them in the same repository as the signed image.

   Note

   You can edit the system-wide registry configuration in the /etc/containers/registries.d/default.yaml file. You can also edit the registry or repository configuration section in any YAML file in the /etc/containers/registries.d directory. All YAML files are read and the filename can be arbitrary. A single scope (default-docker, registry, or namespace) can only exist in one file within the /etc/containers/registries.d directory.

2. Edit the /etc/containers/policy.json file to enforce sigstore signature presence:

   ...
   "transports": {
               "docker": {
                   "<registry>/<namespace>": [
                       {
                           "type": "sigstoreSigned",
                           "keyPath": "/some/path/to/cosign.pub"
                       }
                   ]
               }
           }
   ...

   By modifying the /etc/containers/policy.json configuration file, you change the trust policy configuration. Podman, Buildah, and Skopeo enforce the existence of the container image signatures.

3. Pull the image:

   $ podman pull <registry>/<namespace>/<image>