Verifying image signatures

Digital signatures provide a way for consumers of content to ensure that what they download is both authentic (it originated from the expected source) and has integrity (it is what we expect it to be). Some images for IBM Cloud Pak® for Integration are signed. This page describes how to verify the signatures on those images.

Prerequisites

To perform signature verification:

Your machine must have these command line tools installed (they can usually be installed on Linux using the package manager):

The IBM Cloud Pak for Integration public keys must exist on the same machine as the one used previously. There are three public keys: one for images published before 2022-07-22, one for images published between 2022-07-23 and 2023-03-22, and one for images published after 2023-03-22. Copy the following text block exactly as shown into a text editor, and save it in a file named cp4i-public.gpg:

You must have a list of images to verify. To get a current list of container images used in Cloud Pak for Integration (image names and tags), refer to the procedure in Downloading container images.
Note: The following procedure uses the example image icr.io/cpopen/ibm-integration-platform-navigator-catalog:0.0.0-0000-00-00-0000-a1234567, which is an example for demonstration purposes, not something you can use in your own implementation.

Procedure

Import the Cloud Pak for Integration public key on the machine you prepared according to the Prerequisites section:
```
sudo gpg2 --import cp4i-public.gpg
```
This step needs to be done only once on each machine you use for signature verification.
Calculate the fingerprints:
```
fingerprint=$(sudo gpg2 --fingerprint --with-colons | grep 'cp4i\|ibm' -B1 | grep fpr | tr -d 'fpr:')
```
This command stores the fingerprints for all keys in an environment variable called fingerprint, which is needed to verify the signature. When you exit your shell session, the variable will be deleted. The next time you log in to your machine, you can set it again by rerunning the command.
Create a directory for the image and use skopeo to pull it into local storage:
```
mkdir images
skopeo copy docker://icr.io/cpopen/ibm-integration-platform-navigator-catalog:0.0.0-0000-00-00-0000-a1234567 dir:./images
```
This command downloads the image as a set of files and places them in the images directory (or another directory that you choose).
Tip: One of these files is a manifest file named images/manifest.json, and a signature file named images/signature-1. You reference both these files in the next step (in the command to verify the signature).

Verify the signature:

for fp in ${fingerprint}; do sudo skopeo standalone-verify ./images/manifest.json icr.io/cpopen/ibm-integration-platform-navigator-catalog:0.0.0-0000-00-00-0000-a1234567 ${fp} ./images/signature-1; done

You get a confirmation similar to this:

FATA[0000] Error verifying signature: Signature by 0000000000000000000000000000000000000000 does not match expected fingerprint 1111111111111111111111111111111111111111
FATA[0000] Error verifying signature: Signature by 0000000000000000000000000000000000000000 does not match expected fingerprint 2222222222222222222222222222222222222222
Signature verified, digest sha256:0000000000000000000000000000000000000000000000000000000000000000

In this case, the image has not been signed by the first key or the second key, which is the cause of the first two errors. However, it has been verified as signed by the final key. If the image to be verified is signed by one of the other keys, the message order will be different.