GPG-Schlüssel generieren

Artefakte, die mithilfe der Continuous-Integration-Toolchain von IBM Cloud DevSecOps erstellt und im Inventar erfasst wurden, müssen signiert werden, bevor sie in der Produktion bereitgestellt werden. Die Continuous-Integration-Pipeline nutzt Skopeo als Standardtool, um die Signierung von Artefakten zu ermöglichen.

Erstellen und speichern Sie einen GPG-Schlüssel, der von der DevSecOps-Pipeline für kontinuierliche Integration entweder automatisch oder manuell verwendet wird.

GPG-Schlüssel automatisch generieren

Mit dieser Methode generiert die Vorlage den GPG-Schlüssel für Sie. Geben Sie den Namen und die E-Mail-Adresse für die Schlüsselgenerierung ein, indem Sie die folgenden Schritte ausführen:

  1. Rufen Sie die Artefaktsignierung auf und klicken Sie auf New.

    Bildsignierung
    Artefaktsignierung

  2. Im Fenster werden die Felder name und email vorab mit dem Toolchain-Namen und der E-Mail-ID gefüllt. Ändern Sie den Namen und die E-Mail-ID so, dass sie Ihren GPG-Schlüsselanforderungen entsprechen. Sie können die Schlüssel auch in Ihrem geheimen Schlüssel-Provider speichern, indem Sie das Feld auswählen.

    Name und E-Mail ändern
    Name und E-Mail ändern

  3. Nachdem der Schlüssel generiert wurde, können Sie ihn zu Referenzzwecken kopieren.

    Image-Signaturzertifikat
    Abbildung 3 Artifact-Signaturzertifikat

Der kopierte Schlüssel hat das Format base64. Entschlüsseln Sie den Schlüssel, bevor Sie ihn in Ihren Schlüsselanhänger einführen. echo <encoded_gpg_key> | base64 --decode

Einen GPG-Schlüssel manuell erstellen

GPG-Befehlszeilentools herunterladen und installieren

Laden Sie die GPG-Befehlszeilentools für Ihr Betriebssystem herunter und installieren Sie sie. Gehen Sie zum Abschnitt „Binärversionen“ auf GnuPG, um die Tools für Ihr Betriebssystem herunterzuladen.

Mac OS X

  • Laden Sie Mac GPGherunter und installieren Sie es.
  • Überprüfen Sie die installierte GPG-Version. Führen Sie in der Befehlszeile den folgenden Befehl aus:
$ gpg --version
gpg (GnuPG) 2.3.1
libgcrypt 1.9.3
Copyright (C) 2021 Free Software Foundation, Inc.
  • Bei GPG-Versionen vor 2.3.1 ist es möglicherweise nicht möglich, die Option --passphrase='' zu verwenden. In diesem Fall können Sie das Kennwort im folgenden Dialog übergehen, indem Sie die Eingabetaste drücken, wenn Sie dazu aufgefordert werden.

Windows™

  • Herunterladen und installieren GitBash (erforderlich für die Kodierung „ base64 “).
  • Überprüfen Sie die installierte GPG-Version. Führen Sie den folgenden Befehl in der Eingabeaufforderung Git bash aus:
$ gpg --version
gpg (GnuPG) 2.2.27
libgcrypt 1.8.7
Copyright (C) 2021 g10 Code GmbH

API-Schlüssel generieren

Lassen Sie die Kennphrase und das Feld leer, wenn der Befehl generate-key ein Dialogfenster öffnet, in dem Sie zur Eingabe einer Kennphrase aufgefordert werden. Dies ist eine Einschränkung des Dienstprogramms „skopeo“ bei der Bildsignierung, da die Pipeline keinen privaten Schlüssel akzeptieren kann, der durch eine Passphrase geschützt ist. Wenn Sie die Passphrase bei der Erstellung angeben, kann Ihre Pipeline das Zertifikat nicht entschlüsseln, und Ihre Pipeline scheitert beim Schritt der Image-Signierung. Beachten Sie, dass dies auch für das Signieren von GIT-Tags gilt.

Mac OS X und Linux™

Führen Sie in Ihrer Shell-Eingabeaufforderung den folgenden Befehl aus:

gpg --pinentry-mode loopback --passphrase='' --generate-key
  • Geben Sie Ihren Namen und Ihre E-Mail-Adresse ein.
  • Geben Sie „O“ ein, um die Schlüsselerstellung zu starten.
  • Nachdem der Schlüssel generiert wurde, wählen Sie die Option O.

Windows™

GPG-Version > 1.4

Führen Sie an der GitBash-Eingabeaufforderung den folgenden Befehl aus:

gpg --pinentry-mode loopback --passphrase='' --generate-key
  • Geben Sie Ihren Namen in das Feld „ Echter Name “ ein.
  • Geben Sie Ihre E-Mail-Adresse im Feld E-Mail-Adresse ein.
  • Geben Sie „O“ ein, um die Schlüsselerstellung zu starten.
  • Nachdem der Schlüssel generiert wurde, wählen Sie die Option O.

GPG-Version < 1.4 (oder ein Fehler beim vorherigen Befehl)

Führen Sie an der GitBash-Eingabeaufforderung den folgenden Befehl aus:

gpg --gen-key
  • Schlüsselart: Wählen Sie die Standardoption (1) „RSA“ und „RSA“ (Standard)
  • Schlüsselgröße: Standardwert beibehalten (2048)
  • Schlüsselgültigkeit: Behalten Sie den Standardwert 0 bei. Dies liegt daran, dass der Wertschlüssel 0 nicht abläuft.
  • Bestätigen Sie Ihre Auswahl: Geben Sie „y“ ein.
  • Geben Sie Ihren Namen in das Feld Realer Name ein.
  • Geben Sie Ihre E-Mail-Adresse im Feld E-Mail-Adresse ein.
  • Geben Sie „O“ ein, um die Schlüsselerstellung zu starten.
  • Nachdem der Schlüssel generiert wurde, wählen Sie die Option O.

Schlüsselerstellung überprüfen

Überprüfen Sie, ob der GPG-Schlüssel erstellt wurde. Führen Sie in der Eingabeaufforderung den folgenden Befehl aus:

gpg --list-keys

Vergewissern Sie sich, dass Ihr Schlüssel aufgelistet ist. Beispielausgabe unter 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

Schlüssel exportieren

Dieser Schritt ist optional. Führen Sie diesen Befehl aus, um sicherzustellen, dass der GPG-Schlüssel exportiert werden kann.

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

Der exportierte unformatierte Schlüssel darf nicht direkt kopiert werden. Es wird empfohlen, den in diesem Schritt generierten Schlüssel sicher in Ihrer „ Key Protect “-Instanz oder Ihrer „ Secrets Manager “-Instanz zu speichern. Weitere Details finden Sie in den nächsten Abschnitten.

Schlüssel speichern

Der GPG-Schlüssel muss auf einem der folgenden Wege für die CI-Pipeline bereitgestellt werden:

  • In IBM® Key Protect for IBM Cloud® gespeichert
  • In IBM Cloud® Secrets Manager gespeichert
  • Direkt in der CI-Toolchain gespeichert

Stellen Sie sicher, dass der Schlüssel im korrekten Format kopiert wird, um zu verhindern, dass aufgrund eines Importfehlers ein Signierungsfehler für die CI-Pipeline auftritt. Verwenden Sie im folgenden Befehl „ pbcopy “ ( Mac OS X ) oder „ clip “ (Windows Git bash), um den Schlüsselinhalt in die Zwischenablage zu kopieren.

Schlüssel in Key Protect speichern

Exportieren Sie den GPG-Schlüssel und kopieren Sie ihn in die Zwischenablage.

Die GPG-Schlüssel muss mit einer Double- base64-Verschlüsselung versehen werden, bevor Sie sie in Ihrer „ Key Protect “-Instanz speichern.

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. Wählen Sie in der IBM Cloud-Konsole die Key Protect-Instanz aus, in der Sie den mit den obigen Schritten generierten GPG-Schlüssel speichern wollen.

  2. Klicken Sie auf das Symbol Hinzufügen +, um der Instanz einen neuen Schlüssel hinzuzufügen.

  3. Wählen Sie die Option „ Eigenen Schlüssel importieren “.

  4. Wählen Sie „ Wählen Sie einen Schlüsseltyp aus “ als „ Standardschlüssel “ aus.

  5. Geben Sie im Feld „ Schlüsselname “ den entsprechenden Namen ein. Der gespeicherte GPG-Schlüssel kann später anhand dieses Schlüsselnamens abgerufen werden.

  6. Fügen Sie den zuvor exportierten Schlüssel in das Feld „Schlüsselmaterial“ ein.

    Achten Sie darauf, dass beim Kopieren und Einfügen des Schlüssels in das Feld „Schlüsselmaterial“ am Ende des Schlüssels keine zusätzliche Zeile steht.

  7. Wählen Sie die Option „Schlüsselbund auswählen“ als Standard aus.

  8. Klicken Sie auf Schlüssel hinzufügen, um den Schlüssel zu Ihrem Key Protect hinzuzufügen.

    Den Schlüssel zum Schlüsselschutz hinzufügen
    Den Schlüssel zum Schlüsselschutz hinzufügen

Weitere Informationen zu Key Protect finden Sie in der Key Protect-Dokumentation.

Schlüssel in Secrets Manager speichern

Die einfache base64-Codierung des GPG-Schlüssels ist erforderlich, bevor er in Ihrer Secrets Manager-Instanz gespeichert wird.

Exportieren Sie den GPG-Schlüssel und kopieren Sie ihn in die Zwischenablage.

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. Wählen Sie in der IBM Cloud-Konsole die Secrets Manager-Instanz aus, in der Sie den mit den obigen Schritten generierten GPG-Schlüssel speichern wollen.

  2. Klicken Sie auf das Symbol Hinzufügen +, um der Instanz einen neuen Schlüssel hinzuzufügen.

  3. Wählen Sie die Option „ Anderer Geheimtyp “ aus.

    Andere geheime Art
    Andere geheime Art

  4. Wählen Sie Standardschlüssel für die Option Schlüsseltyp auswählen aus.

  5. Geben Sie im Feld „Name“ einen passenden Namen ein. Der gespeicherte GPG-Schlüssel kann später durch diesen Namen abgerufen werden.

  6. Wählen Sie die Option „ Geheimer Wert “ aus und fügen Sie den zuvor exportierten Schlüssel in das Feld „ Geheimer Wert “ ein.

    Achten Sie darauf, dass beim Kopieren des Schlüssels und Einfügen in das Feld „Secret value“ am Ende des Schlüssels keine zusätzliche Zeile steht.

  7. Fügen Sie den Schlüssel zu Ihrer Key Protect-Instanz hinzu, indem Sie auf das Symbol Hinzufügen klicken.

    Hinzufügen des Schlüssels
    Hinzufügen des Schlüssels

Weitere Informationen zu Secrets Manager enthält der Abschnitt Einführung in Secrets Manager.

Privaten Schlüssel exportieren und direkt in der CI-Pipeline speichern

Dieser Ansatz wird nicht empfohlen und sollte nur zu Versuchszwecken verwendet werden. Verwenden Sie Key Protect oder Secrets Manager zum Speichern der Schlüssel. Weitere Informationen finden Sie unter Speicher für geheime Schlüssel konfigurieren.

Die einfache base64-Codierung des GPG-Schlüssels ist erforderlich, bevor er als geschützte Pipeline-Eigenschaft gespeichert wird.

Speichern Sie den GPG-Schlüssel sicher in einer Key Protect- oder Secrets Manager-Instanz.

Mac OS X / Linux™

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

Windows™

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

Konfigurieren der Registrierungsanmeldedaten für die Signierung

Zum Signieren von Container-Images benötigt die Pipeline Anmeldedaten für die Authentifizierung bei der Container-Registry. Die „ DevSecOps “-Pipeline unterstützt die dynamische Auflösung von Anmeldedaten zur Laufzeit, sodass Sie Anmeldedaten auf verschiedene Arten konfigurieren können, wobei automatische Ausweichmechanismen zum Einsatz kommen.

Hierarchie der Anmeldeinformationen

Die Pipeline löst sowohl den Benutzernamen als auch den API-Schlüssel zur Laufzeit dynamisch anhand der folgenden Hierarchie auf.

Wenn eine Überschreibung des Signaturziels über gara-destination-registry und gara-destination-namespace konfiguriert wird und zudem gara-destination-apikey angegeben ist, räumt die Pipeline gara-destination-apikey bei der Authentifizierung gegenüber der Zielregistrierungsstelle höchste Priorität ein. Andernfalls greift die unten beschriebene Anmeldeinformationsauflösung für das Ziel-Image.

Reihenfolge der API-Schlüsselauflösung:

  1. Namespace-spezifischer API-Schlüssel: signing-token-apikey-{registry}-{namespace} (Geheimnis)
  2. Registry-spezifischer API-Schlüssel: signing-token-apikey-{registry} (geheim)
  3. Docker Konfigurations-JSON: signing-dockerconfigjson (geheim)
  4. ICR-spezifische Fallbacks:
    • ciso-ibmcloud-api-key (geheim)
    • ibmcloud-api-key (geheim)

Reihenfolge der Benutzernamenauflösung:

  1. Namespace-spezifischer Benutzername: signing-token-username-{registry}-{namespace} (Umgebungsvariable)
  2. Registrierungsspezifischer Benutzername: signing-token-username-{registry} (Umgebungsvariable)
  3. Standard: iamapikey (sofern kein Benutzername konfiguriert ist)

Dabei gilt:

  • {registry} ist der Hostname der Registrierungsstelle (z. B. us.icr.io, de.icr.io)
  • {namespace} ist der vollständige Namespace-Pfad, bei dem Schrägstriche und Punkte durch Unterstriche ersetzt wurden (z. B. my_namespace_path)

Konfigurieren von namensraumspezifischen Anmeldedaten

Für eine detaillierte Zugriffskontrolle können Sie Anmeldeinformationen konfigurieren, die für einen bestimmten Registrierungsnamensraum gelten:

API-Schlüssel (Geheimnis): signing-token-apikey-{registry}-{namespace}

Benutzername (Umgebungsvariable): signing-token-username-{registry}-{namespace}

Beispiel: Für ein Bild us.icr.io/my-namespace/my-app:latest

  • Registrierung: us.icr.io
  • Namensraum: my-namespace
  • Geheimer API-Schlüssel: signing-token-apikey-us.icr.io-my_namespace
  • Umgebungsvariable „Benutzername“: signing-token-username-us.icr.io-my_namespace
  • Wenn kein Benutzername angegeben wird, wird standardmäßig Folgendes verwendet: iamapikey

Konfigurieren von registrierungsspezifischen Anmeldedaten

Für einen umfassenderen Zugriff auf alle Namensräume in einer Registrierungsstelle:

API-Schlüssel (Geheimnis): signing-token-apikey-{registry}

Benutzername (Umgebungsvariable): signing-token-username-{registry}

Beispiel: Für jedes Bild in us.icr.io

  • Geheimer API-Schlüssel: signing-token-apikey-us.icr.io
  • Umgebungsvariable „Benutzername“: signing-token-username-us.icr.io
  • Wenn kein Benutzername angegeben wird, wird standardmäßig Folgendes verwendet: iamapikey

Konfigurieren der JSON-Konfigurationsdatei für „ Docker “

Sie können eine JSON-Konfigurationsdatei unter base64-encoded Docker bereitstellen, die Anmeldedaten für mehrere Registries enthält:

Geheimer Name: signing-dockerconfigjson

Format: Base64-encoded JSON, das dem Format von Docker unter config.json entspricht:

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

Die Pipeline gleicht zunächst den spezifischsten Pfad ab, wodurch Überschreibungen auf Namespace-Ebene innerhalb der Konfiguration unter „ Docker “ möglich sind.

Beispielkonfiguration

Für ein Bild us.icr.io/production/my-app:v1.0.0:

Option 1: Namespace-spezifisch (für die Produktion empfohlen)

  • API-Schlüssel: signing-token-apikey-us.icr.io-production = your-namespace-api-key
  • Umgebungsvariable für den Benutzernamen (optional): signing-token-username-us.icr.io-production = iamapikey
  • Wenn kein Benutzername angegeben wird, wird standardmäßig iamapikey

Option 2: Registrierungsweit

  • API-Schlüssel: signing-token-apikey-us.icr.io = your-registry-api-key
  • Umgebungsvariable für den Benutzernamen (optional): signing-token-username-us.icr.io = iamapikey
  • Wenn kein Benutzername angegeben wird, wird standardmäßig iamapikey

Option 3: JSON-Konfigurationsdatei für „ Docker “

  • Geheimnis: signing-dockerconfigjson = base64-encoded-docker-config
  • Der Benutzername wird aus der JSON-Konfigurationsdatei „ Docker “ extrahiert

Option 4: Standardwert für „ IBM Cloud “ (automatisch bei ICR)

  • API-Schlüssel: ibmcloud-api-key = your-ibmcloud-api-key
  • Der Benutzername lautet standardmäßig iamapikey