IBM Cloud Docs
Generating a GPG key

Generating a GPG key

Images that are built by the IBM Cloud DevSecOps continuous integration toolchain and recorded in the inventory must be signed before they are deployed to production. The continuous integration pipeline uses Skopeo as the default tool to provide image signing capability.

Create and store a GPG key that is used by the DevSecOps continuous integration pipeline either automatically or manually.

Automatically generate a GPG key

Using this method, the template generates the GPG key for you. Provide the name and email as required for the key generation by completing these steps:

  1. Go to the image signing stage, and click New.

    Image signing
    Figure 1. Image signing

  2. In the window, the name and email fields are prepopulated with the toolchain name and the email ID. Change the name and email ID to reflect your GPG key requirements. You can also store the keys in your secrets provider by selecting the box.

    Change name and email
    Figure 2. Change name and email

  3. After the key is generated, you can copy it for your reference.

    Image signing certificate
    Figure 3 Image signing certificate

The copied key is in base64 format. Decrypt the key before you import it to your key ring.

Manually generate a GPG key

Download and install GPG command-line tools

Download and install the GPG command-line tools for your operating system. Go to the GnuPG binary releases section to download the tools for your operating system.

OS X

  • Download and install Mac GPG.
  • Verify the version of the installed GPG. From the command line, run the following command:
$ gpg --version
gpg (GnuPG) 2.3.1
libgcrypt 1.9.3
Copyright (C) 2021 Free Software Foundation, Inc.
  • For versions of GPG prior to 2.3.1, it might not be possible to use the --passphrase='' option. In this case, you can omit the password in the following dialog by pressing Enter when prompted.

Windows

  • Download and install GitBash (required for base64 encoding).
  • Verify the version of the installed GPG. From the Git bash command prompt, run the following command:
$ gpg --version
gpg (GnuPG) 2.2.27
libgcrypt 1.8.7
Copyright (C) 2021 g10 Code GmbH

Generate a GPG key

Leave the passphrase and repeat field empty if the generate-key command opens a dialog that asks for a passphrase. This is a limitation with the (skopeo) utility of the image signing where the pipeline cannot accept a private key that is protected with a passphrase. If you provide the passphrase during creation, then your pipeline fails to decode the certificate, and your pipeline fails at the image signing step.

OS X and Linux

From your shell prompt, run the following command:

gpg --pinentry-mode loopback --passphrase='' --generate-key
  • Enter Real name your name
  • Enter Email address your email address
  • Enter O to initiate key creation
  • After the key is generated, select option O

Windows

GPG Version > 1.4

From the Git bash command prompt, run the following command:

gpg --pinentry-mode loopback --passphrase='' --generate-key
  • Enter Real name your name
  • Enter Email address your email address
  • Enter O to initiate key creation
  • After the key is generated, select option O

GPG Version < 1.4 (or any failure with previous command)

From the Git bash command prompt, run the following command:

gpg --gen-key
  • kind of key: select Default option (1) RSA and RSA (default)
  • keysize: keep default (2048)
  • key validity: keep default (0 = key does not expire)
  • Confirm your choice: enter y
  • Enter Real name: your name
  • Enter Email address: your email address
  • Enter comment: any comment of your choice
  • Enter O to initiate key creation

Verify the key creation

Verify that the GPG key was created. From the command prompt, run the following command:

gpg --list-keys

Ensure that your key is listed. Example output on Windows:

$ gpg --list-keys
/c/Users/FredSmith/.gnupg/pubring.gpg
-------------------------------------
pub   2048R/1BB354B5 2021-06-08
uid   Fred Smith <fred@company.com>
sub   2048R/F91C39A6 2021-06-08

Export the key

This step is optional. Run this command to ensure that the gpg key can be exported.

gpg --export-secret-key <Email Address>

The raw key that is exported must not be copied directly. It is recommended to securely store the key that is generated in this step in your Key Protect instance or Secrets Manager instance. See the next sections for more details.

Store the key

The GPG key must be provided to the CI pipeline in one of the following ways:

  • Stored in IBM® Key Protect for IBM Cloud®
  • Stored in IBM Cloud® Secrets Manager
  • Stored directly in the CI toolchain

Make sure that the key is copied in the correct format to prevent a CI pipeline signing error due to import failure. Use pbcopy (OS X) or clip (Windows Git bash) in the following command to copy the key content to the clipboard.

Store the key in Key Protect

Double base64 encoding of the GPG key is required before you store it in your Key Protect instance.

Export and copy the GPG key to the clipboard.

OS X 

gpg --export-secret-key <Email Address> | base64 | base64 | pbcopy

Windows

gpg --export-secret-key <Email Address> | base64 -w0 | base64 -w0 | clip

Linux

gpg --export-secret-key <Email Address> | base64 | base64

  1. In your IBM Cloud console, select the Key Protect instance where you want to store the GPG key generated from the previous steps.

  2. Click the Add + icon to add new key to the instance.

  3. Select Import your own key option.

  4. Select Select a key type as Standard Key.

  5. Give appropriate name in the Key name field. The stored GPG key can be retrieved later by this name.

  6. Copy the key as exported earlier in the Key material field.

    Ensure that when you copy the key and paste it in Key material field, there is no extra line at the end of the key.

  7. Select the Choose a key ring option as default.

  8. Add the key to your key protect by clicking the Add key icon.

    Add the key to key protect
    Figure 4. Add the key to key protect

For more information about Key Protect, see the Key Protect docs.

Store the key in Secrets Manager

Single base64 encoding of the GPG key is required before storing it in your Secrets Manager instance.

Export and copy the GPG key to the clipboard.

OS X

gpg --export-secret-key <Email Address> | base64 | pbcopy

Windows

gpg --export-secret-key <Email Address> | base64 -w0 | clip

Linux

gpg --export-secret-key <Email Address> | base64

  1. In your IBM Cloud console, select the Secrets Manager instance where you want to store GPG Key generated from the previous steps.

  2. Click the Add + icon to add new key to the instance.

  3. Select Other secret type option.

    Other secret type
    Figure 5. Other secret type

  4. Select Select a key type as Standard Key.

  5. Give an appropriate name in the Name field. The stored GPG key can be retrieved later by this name.

  6. Choose the option as Secret value and paste the key as exported earlier in the Secret Value field.

    Ensure that when you copy the key and paste it in Secret value field, there is no extra line at the end of the key.

  7. Add the key to your Key Protect instance by clicking the Add icon.

    Add the key
    Figure 6. Add the key

For more information about Secrets Manager, see Getting started with Secrets Manager.

Export the private key and store it directly in the CI pipeline

This approach is not recommended and should be used only for experimentation. Use keyprotect or secrets manager for storing the keys.

Single base64 encoding of the GPG key is required before storing it as a secured pipeline property.

Securely store the GPG key in a Key Protect or Secrets Manager instance.

OS X / Linux

gpg --export-secret-key <Email Address> | base64

Windows

gpg --export-secret-key <Email Address> | base64 -w0