GPG 鍵の生成

IBM Cloud DevSecOps の継続的インテグレーションツールチェーンによって生成され、インベントリに登録されたアーティファクトは、本番環境にデプロイする前に署名する必要があります。 継続的インテグレーション・パイプラインでは、 Skopeo をデフォルトのツールとして使用し、アーティファクトの署名機能を提供します。

DevSecOps 継続的インテグレーション・パイプラインが自動または手動で使用する GPG キーを作成し、保存します。

GPG鍵を自動生成する

この方法を使用すると、テンプレートによって GPG 鍵が自動的に生成されます。 以下の手順を実行して、鍵生成の 名前 および E メール を入力します。

  1. 「成果物の署名」 に移動し、 「新規」 をクリックします。

    画像署名
    アーティファクト署名

  2. このウィンドウでは、 「名前」 フィールドと 「E メール」 フィールドにツールチェーン名と E メール ID が事前に入力されています。 GPG キーの要件を反映するように、名前と E メール ID を変更します。 ボックスを選択して、秘密プロバイダーに鍵を保管することもできます。

    名前とEメールを変更する
    名前とEメールを変更する

  3. 鍵が生成されたら、参照用にコピーすることができます。

    イメージ署名証明書
    図 3 成果物署名証明書

コピーされた鍵は base64 形式です。 キーホルダー にインポートする前に、キーを デコードし てください。 echo <encoded_gpg_key> | base64 --decode

GPG鍵を手動で生成する

GPG コマンド・ライン・ツールのダウンロードとインストール

お使いのオペレーティングシステムに対応 したGPGコマンドラインツールをダウンロードしてインストールしてください。 GnuPG のバイナリリリースページにアクセスし、お使いのオペレーティングシステムに対応したツールをダウンロードしてください。

Mac OS X

  • Mac GPGをダウンロードしてインストールします。
  • インストールした GPG のバージョンを確認します。 コマンド・ラインから、次のコマンドを入力します。
$ gpg --version
gpg (GnuPG) 2.3.1
libgcrypt 1.9.3
Copyright (C) 2021 Free Software Foundation, Inc.
  • 2.3.1 以前のバージョンの GPG では、 --passphrase='' オプションを使用できない場合があります。 この場合、プロンプトが出されたら Enter キーを押して、以下のダイアログでパスワードを省略できます。

Windows™

  • ダウンロードしてインストール GitBash （ base64 エンコーディングに必要です）。
  • インストールした GPG のバージョンを確認します。 Git bash コマンド・プロンプトで以下のコマンドを実行します。
$ gpg --version
gpg (GnuPG) 2.2.27
libgcrypt 1.8.7
Copyright (C) 2021 g10 Code GmbH

GPG 鍵の生成

generate-key コマンドでパスフレーズを要求するダイアログを開く場合は、パスフレーズとフィールドを空のままにします。 これは、画像署名を行う skopeo ユーティリティの制限事項であり、パスフレーズで保護された秘密鍵をパイプラインで受け入れることができません。 作成時にパスフレーズを指定すると、パイプラインは証明書の復号に失敗し、イメージ署名ステップで処理が失敗します。 これはGITタグの署名にも適用できることに注意してください。

Mac OS X そして Linux™

シェルプロンプトで、次のコマンドを実行してください：

gpg --pinentry-mode loopback --passphrase='' --generate-key
  • お名前とメールアドレスを入力してください。
  • 「 O 」を入力して鍵の作成を開始してください。
  • 鍵が生成されたら、オプション O を選択してください。

Windows™

GPG バージョン > 1.4

Git bash コマンド・プロンプトで、以下のコマンドを実行します。

gpg --pinentry-mode loopback --passphrase='' --generate-key
  • 「 本名 」の欄にお名前を入力してください。
  • 「E メール・アドレス」 に E メール・アドレスを入力します。
  • 「O 」を入力して鍵の作成を開始してください。
  • 鍵が生成されたら、オプション O を選択してください。

GPG のバージョンが 1.4 より古い場合（または前のコマンドで何らかの失敗が発生した場合）

Git bash コマンド・プロンプトで、以下のコマンドを実行します。

gpg --gen-key
  • ある種の鍵: 「デフォルト」オプションを選択してください (1) RSA および RSA（既定値）
  • 鍵の長さ ：デフォルトのままにする（2048）
  • key validity: デフォルト値を 0 のままにします。 これは、値キー 0 が期限切れにならないためです。
  • 選択を確認してください： y を入力してください。
  • 「実名」 フィールドに自分の名前を入力します。
  • 「E メール・アドレス」 に E メール・アドレスを入力します。
  • 「 O 」を入力して鍵の作成を開始してください。
  • 鍵が生成されたら、オプション O を選択してください。

鍵の作成の確認

gpg 鍵が作成されたことを確認します。 コマンドプロンプトで、次のコマンドを実行します：

gpg --list-keys

鍵がリストされていることを確認します。 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

鍵のエクスポート

このステップはオプションです。 以下のコマンドを実行して、gpg 鍵がエクスポート可能であることを確認します。

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

エクスポートされたロー鍵を直接コピーしてはなりません。 この手順で生成されたキーは、 Key Protect インスタンスまたは Secrets Manager インスタンスに安全に保管することをお勧めします。 詳しくは、次のセクションを参照してください。

鍵の保管

GPG 鍵は、以下のいずれかの方法で CI パイプラインに提供する必要があります。

  • IBM® Key Protect for IBM Cloud® に保管
  • IBM Cloud® Secrets Manager に保管
  • CI ツールチェーンに直接保管

インポートの失敗によって CI パイプラインの署名エラーが発生しないように、鍵は必ず正しいフォーマットでコピーしてください。 以下のコマンドで、 pbcopy （ Mac OS X ）または clip （Windows Git bash）を使用して、キーの内容をクリップボードにコピーしてください。

Key Protect への鍵の保管

GPG 鍵をエクスポートしてクリップボードにコピーします。

GPGキーを Key Protect インスタンスに保存する前に、 base64 による二重エンコードを行う必要があります。

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. IBM Cloud コンソールで、前のステップで生成した GPG 鍵を保管する Key Protect インスタンスを選択します。

  2. 「追加 + (Add +)」 アイコンをクリックして、新しい鍵をインスタンスに追加します。

  3. 「 独自のキーをインポート 」オプションを選択してください。

  4. 「 標準キー 」としてキーの種類を選択してください。

  5. 「 キー名 」フィールドに適切な名前を入力してください。 保存されたGPG鍵は、後でこの鍵名を使って取得できます。

  6. 先ほどエクスポートしたキーを「 キー素材 」フィールドに貼り付けてください。

    キーをコピーして「 Key material 」フィールドに貼り付ける際は、キーの末尾に余分な改行が入っていないことを確認してください。

  7. 「 キーリングを選択 」オプションをデフォルトとして設定します。

  8. 「鍵の追加」 をクリックして、鍵を 鍵保護に追加します。

    キープロテクトにキーを追加する
    キープロテクトにキーを追加する

Key Protect について詳しくは、Key Protect の資料を参照してください。

Secrets Manager への鍵の保管

GPG 鍵を Secrets Manager インスタンスに保管する前に、GPG 鍵の単一 base64 エンコードが必要です。

GPG 鍵をエクスポートしてクリップボードにコピーします。

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. IBM Cloud コンソールで、前のステップで生成した GPG 鍵を保管する Secrets Manager インスタンスを選択します。

  2. 「追加 + (Add +)」 アイコンをクリックして、新しい鍵をインスタンスに追加します。

  3. 「 その他の秘密鍵タイプ 」オプションを選択してください。

    その他の秘密タイプ
    その他の秘密タイプ

  4. オプション 「Select a key type」 で 「Standard Key」 タイプを選択します。

  5. 「 名前 」欄に適切な名前を入力してください。 保管された GPG 鍵は、後からこの名前を使用して取り出せます。

  6. オプションとして「 シークレット値 」を選択し、先ほどエクスポートしたキーを「 シークレット値 」フィールドに貼り付けてください。

    キーをコピーして「 Secret」値のフィールドに貼り付ける際は、キーの末尾に余分な改行が入っていないことを確認してください。

  7. 「追加」 アイコンをクリックして、 Key Protect インスタンスに鍵を追加します。

    キーを追加
    キーを追加
    キーを追加

Secrets Manager について詳しくは、Secrets Manager の概要を参照してください。

秘密鍵をエクスポートして CI パイプラインに直接保管する

この方法は推奨されず、実験目的でのみ使用すべきです。 鍵の保存には、 Key Protect または Secrets Manager をご利用ください。 詳しくは、 シークレット・ストアの構成 を参照してください。

GPG 鍵を保護されたパイプライン・プロパティーとして保管する前に、GPG 鍵の単一 base64 エンコードが必要です。

GPG 鍵は Key Protect または Secrets Manager のインスタンスに安全に保管してください。

Mac OS X / Linux™

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

Windows™

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

署名用のレジストリ認証情報の設定

コンテナイメージに署名する際、パイプラインはコンテナレジストリへの認証に必要な認証情報が必要です。 DevSecOps パイプラインは、実行時の動的な認証情報の解決をサポートしており、自動フォールバック機能を利用して、さまざまな方法で認証情報を設定することができます。

認証情報の解決階層

このパイプラインは、実行時に以下の階層構造に従って、ユーザー名とAPIキーの両方の認証情報を動的に解決します。

gara-destination-registry および gara-destination-namespace を使用して署名先の上書きが設定され、かつ gara-destination-apikey も指定されている場合、パイプラインは宛先レジストリへの認証において gara-destination-apikey を最優先します。 それ以外の場合は、宛先イメージに対して以下の認証情報の解決が適用されます。

APIキーの解決順序：

  1. ネームスペース固有のAPIキー ： signing-token-apikey-{registry}-{namespace} (シークレット)
  2. レジストリ固有のAPIキー ： signing-token-apikey-{registry} （シークレット）
  3. Docker 設定JSON: signing-dockerconfigjson (非公開)
  4. ICR固有のフォールバック ：
    • ciso-ibmcloud-api-key （秘密）
    • ibmcloud-api-key （秘密）

ユーザー名の解決順序：

  1. 名前空間固有のユーザー名: signing-token-username-{registry}-{namespace} (環境変数)
  2. レジストリ固有のユーザー名 ： signing-token-username-{registry} （環境変数）
  3. デフォルト: iamapikey （ユーザー名が設定されていない場合）

ここで、

  • {registry} レジストリのホスト名です（例： us.icr.io、 de.icr.io ）
  • {namespace} スラッシュとドットがアンダースコアに置き換えられた完全な名前空間パスです（例： my_namespace_path ）

ネームスペース固有の認証情報の設定

きめ細かなアクセス制御を行うには、レジストリの名前空間ごとに固有の認証情報を設定できます：

APIキー（シークレット） ： signing-token-apikey-{registry}-{namespace}

ユーザー名（環境変数） ： signing-token-username-{registry}-{namespace}

例 ：画像の場合 us.icr.io/my-namespace/my-app:latest

  • registry: us.icr.io
  • 名前空間： my-namespace
  • APIキーのシークレット： signing-token-apikey-us.icr.io-my_namespace
  • ユーザー名環境変数： signing-token-username-us.icr.io-my_namespace
  • ユーザー名が指定されていない場合、デフォルトは次の通りです： iamapikey

レジストリ固有の認証情報の設定

レジストリ内のすべての名前空間に広くアクセスするには：

APIキー（シークレット） ： signing-token-apikey-{registry}

ユーザー名（環境変数） ： signing-token-username-{registry}

例 ：内の任意の画像について us.icr.io

  • APIキーのシークレット： signing-token-apikey-us.icr.io
  • ユーザー名環境変数： signing-token-username-us.icr.io
  • ユーザー名が指定されていない場合、デフォルトは次の通りです： iamapikey

Docker の設定JSONファイルの設定

複数のレジストリの認証情報を含む、 base64-encoded Docker の設定JSONを指定できます：

秘密の名前 ： signing-dockerconfigjson

形式 ： Base64-encoded （ Docker の config.json 形式に準拠した JSON）：

{
  "auths": {
    "us.icr.io": {
      "username": "iamapikey",
      "password": "your-api-key"
    },
    "us.icr.io/my-namespace": {
      "username": "iamapikey",
      "password": "namespace-specific-key"
    }
  }
}

パイプラインは最も具体的なパスから順に一致させるため、 Docker の設定内で名前空間レベルでの上書きが可能になります。

構成の例

画像については us.icr.io/production/my-app:v1.0.0 をご覧ください：

オプション 1: 名前空間固有（本番環境での使用を推奨）

  • APIキーのシークレット： signing-token-apikey-us.icr.io-production = your-namespace-api-key
  • ユーザー名環境変数（任意）： signing-token-username-us.icr.io-production = iamapikey
  • ユーザー名が指定されていない場合、デフォルトでは iamapikey

オプション 2: レジストリ全体

  • APIキーのシークレット： signing-token-apikey-us.icr.io = your-registry-api-key
  • ユーザー名環境変数（任意）： signing-token-username-us.icr.io = iamapikey
  • ユーザー名が指定されていない場合、デフォルトでは iamapikey

オプション 3: Docker の設定 JSON

  • 秘密： signing-dockerconfigjson = base64-encoded-docker-config
  • ユーザー名は、 Docker の設定JSONから抽出されます

オプション 4: IBM Cloud （デフォルト設定。ICRの場合は自動）

  • APIキーのシークレット： ibmcloud-api-key = your-ibmcloud-api-key
  • ユーザー名はデフォルトで iamapikey