Image Signature Verification

Edit online

To verify that only IBM-signed images are pulled into the cluster’s registry, set up image signature verification. This step is optional.

Prerequisites

  1. Access to IBM Entitled Registry (ER).
  2. The skopeo package is installed. For installation guidance, see https://github.com/containers/skopeo.
  3. Access to the destination image repository where images are pulled.
  4. Download and extract key and certificate files:
    1. Download the ZIP file and extract its contents. To download the ZIP file, click here .
    2. Extracted files:
      • sspkey.pub.asc – Public key for verifying the image signature.
      • sspkey.pem.cer and sspkey.pem.chain – Certificate files used to validate the signing chain.

Verifying the Image

Follow the below steps to verify the image:
  1. Automatic Signature Verification:
  2. Policy Configuration: Create or update the policy file located at /etc/containers/policy.json and set it according to the configuration shared in (YAML format). 
    
{
  "default": [
    {
      "type": "reject"
    }
  ],
  "transports": {
    "docker": {
      "cp.icr.io/cp/ibm-ssp-cm": [
        {
          "type": "signedBy",
          "keyType": "GPGKeys",
          "keyPath": "/path/to/sspkey.pub.asc"
        }
      ]
    }
  }
}
    Note: For unsigned images, set "type":"insecureAcceptAnything" for IBM Production Entitled Registry in the /etc/containers/policy.json file.
    1. Pull the Image: Use the following command to pull images to your local registry: 
      skopeo copy docker://cp.icr.io/cp/ibm-ssp-cm/<imagename>:<tag> docker://<local_repository>:<tag> --src-creds iamapikey:key --dest-creds username:password
  3. Manual Signature Verification:
    1. Copy the Public Key to the local filesystem for verification - sspkey.pub.gpg.
    2. Import the Public Key to the GPG keystore: 
      sudo gpg --import path/to/sspkey.pub.asc
    3. Get the fingerprint for the imported key 
      sudo gpg -k

      or

      export FINGERPRINT=$(gpg --fingerprint --with-colons | grep fpr | tr -d 'fpr:')
    4. Pull the Image Locally: 
      skopeo copy docker://cp.icr.io/cp/ibm-ssp-cm/<imagename>:<tag> dir:<imagedir> --src-creds="iamapikey:key"
    5. Verify the Signature: 
      skopeo standalone-verify <imagedir>/manifest.json icr.io/cp/ibm-ssp-cm/<imagename>:<tag> <gpgkeyfingerprint> <imagedir>/signature-1
    6. Expected Result: 
      Signature verified, digest sha256:<xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  4. Certificate Verification
    • Compare the Certificate and Public Key:
      • Display the certificate details: 
        openssl x509 -text -in sspkey.pem.cer
##shows the certificate details, e.g. it is signed by IBM and Digicert
      • Display public key details: 
        gpg -v --list-packets sspkey.pub.gpg
#shows the public key details

    • Modulus and Exponent Verification:

      Certificate Modulus: 
      00:cf:61:02:67:1b:90:09:34:0b:be:f8:8b:16:2f: 5a:73:57:ab:02:a2:42:a3:05:ee:9b:ec:40:8c:b7:Exponent: 65537 (0x10001)
      Public key: 
      ... pkey[0]: CF6102671B9009340BBEF88B162F5A7357AB02A242A305EE9B 
pkey[1]: 010001
      • Ensure that the public key modulus and exponent match the certificate’s details.

    • Certificate Validity Check: 
      openssl ocsp -no_nonce -issuer path/to/sspkey.pem.chain -cert path/to/sspkey.pem.cer -VAfile path/to/sspkey.pem.chain -text -url http://ocsp.digicert.com -respout ocsptest

    Note: The certificate is refreshed every two years.
    Note: The procedure described above applies to CM image signature verification. When performing Engine or Perimeter Server (PS) image signature verification, substitute the repository name ibm-ssp-cm with ibm-ssp-engine or ibm-ssp-ps, depending on the image being verified.