IBM Cloud Docs
Generating a GPG key

Generating a GPG key

Artifacts 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 artifact 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. Enter the name and email for the key generation by completing these steps:

  1. Go to the Artifact signing and click New.

    Image signing
    Artifact 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
    Change name and email

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

    Image signing certificate
    Figure 3 Artifact signing certificate

The copied key is in base64 format. Decode the key before you import it to your key ring. echo <encoded_gpg_key> | base64 --decode

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.

Mac 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 before 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. Run the following command in the Git bash command prompt:
$ 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 the 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.

Mac OS X and Linux™

From your shell prompt, run the following command:

gpg --pinentry-mode loopback --passphrase='' --generate-key
  • Enter your name and 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 your name in the Real name field.
  • Enter your email address in the Email address.
  • Enter O to initiate the 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 the default value as 0. This is because the value key 0 does not expire.
  • Confirm your choice: enter y.
  • Enter your your name in the Real name field.
  • Enter your email address in the Email address.
  • Enter O to initiate key creation.
  • After the key is generated, select option O.

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 (Mac 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

Export and copy the GPG key to the clipboard.

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

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 the appropriate name in the Key name field. The stored GPG key can be retrieved later by this key 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. Click Add key to add the key to your key protect.

    Add the key to key protect
    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
    Other secret type

  4. Select Standard Key type for the option Select a key type.

  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 the 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
    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 Key Protect or Secrets Manager for storing the keys. For more information, see Configuring the secrets stores

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.

Mac OS X / Linux™

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

Windows™

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