Fingerabdrücke verwenden, um die Identitäten von Paketversionen zu überprüfen

Mit Artefakt-Fingerabdrücken können Sie Pakete in Artifact Registry-Repositories eindeutig identifizieren.

Wenn Sie ein Paket in ein Repository übertragen, berechnet Artifact Registry einen Fingerabdruck für diese Paketversion. Der Fingerabdruck ist eine kryptografisch unveränderliche Referenz, mit der Sie prüfen können, ob das Paket beim Übertragen zwischen Google Cloud-Systemen wie Compute Engine und Cloud Build geändert wurde. Nachdem Sie den Fingerabdruck Ihres Pakets abgerufen haben, können Sie ihn verwenden, um sicherzustellen, dass Ihr Paket bei bestimmten Artifact Registry API-Anfragen gültig ist. Sie können auch lokale und Repository-Instanzen desselben Pakets validieren, indem Sie den lokalen Fingerabdruck manuell berechnen und mit dem Fingerabdruck im Repository vergleichen.

Hinweis

Aktivieren Sie Artifact Registry sowie die Artifact Registry API und installieren Sie die Google Cloud CLI.
(Optional) Konfigurieren Sie die Standardeinstellungen für gcloud-Befehle.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle Artifact Registry Reader (roles/artifactregistry.reader) für das Google Cloud Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Aufrufen von Fingerabdrücken von Paketversionen in Artifact Registry-Repositories benötigen. Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Fingerabdruck einer Paketversion in Ihrem Repository abrufen

Fingerabdrücke haben die folgende Struktur:

VERSION@DIRSUM_SHA256:HASH_VALUE

Geben Sie in der Google Cloud CLI Folgendes ein, um den Fingerabdruck einer Paketversion in einem Artifact Registry-Repository abzurufen:

gcloud artifacts versions describe VERSION --repository=REPOSITORY --location=LOCATION --package=PACKAGE_NAME

Wobei:

VERSION ist die Version Ihres Pakets, z. B. 1.0543.
REPOSITORY ist das Repository mit dem Paket, das Sie bewerten.
LOCATION ist der regionale oder multiregionale Standort für das Repository. Sie können dieses Flag weglassen, wenn Sie einen Standard-Speicherort festgelegt haben.
PACKAGE_NAME ist der Name des Pakets.

Die Antwort sieht so aus:

fingerprints:
- type: DIRSUM_SHA256
  value: 7c07b910c6dd6df6984a5591d00ad0074fe24cd81145d2c681cdfda3b3d65a04
name: projects/test-project/locations/us-west1/repositories/test-repo/packages/test-pkg/versions/v1
updateTime: '2025-08-15T00:03:41.809228Z'

Die vollständige Adresse des Fingerabdrucks besteht aus der Paketversion, gefolgt vom Fingerabdrucktyp und dann dem Hashwert. In diesem Beispiel ist die Fingerabdruckadresse VERSION@DIRSUM_SHA256:7c07b910c6dd6df6984a5591d00ad0074fe24cd81145d2c681cdfda3b3d65a04.

Fingerabdrücke als unveränderliche Referenzen in der Artifact Registry API validieren

Bei bestimmten Artifact Registry API-Anfragen wird ein Paket aus Ihrem Repository validiert, wenn der Fingerabdruck dieses Pakets so formatiert ist:

VERSION@DIRSUM_SHA256:HASH_VALUE

Sie möchten beispielsweise eine Anlage für ein Paket in Ihrem Repository erstellen. Im folgenden Befehl wird das für target definierte Paket so formatiert, dass Artifact Registry auch den Fingerabdruck des Pakets validiert:

  gcloud artifacts attachments create my-attachment --target='projects/test-project/locations/us-west1/repositories/test-repo/packages/test-pkg/versions/v1@dirsum_sha256:30330c6b65a26ebf1a13e1b9ded4068b4c36d72ed3b62226e3243b5bee18fd31' --attachment-type="application/vnd.in-toto+json" --attachment-namespace="mynamespace.com" --files=att.txt

Wenn der angegebene Fingerabdruck nicht mit dem Fingerabdruck der aktuellen Version übereinstimmt, lehnt Artifact Registry die API-Anfrage ab und zeigt den Fehler failed_precondition an.

Bei den folgenden Anfragen werden die angegebenen Fingerabdrücke validiert, wenn sie über API-Bibliotheken, die Google Cloud CLI und curl übergeben werden:

Bei den folgenden Anfragen werden Fingerabdrücke validiert, wenn sie über API-Bibliotheken und curl übergeben werden:

ListAttachments

Prüfen, ob lokale und Repository-Instanzen eines Pakets identisch sind

Um zu prüfen, ob ein Paket beim Übertragen zwischenGoogle Cloud -Systemen geändert wurde, berechnen Sie den Fingerabdruck einer Instanz dieses Pakets manuell außerhalb Ihres Repositorys.

So berechnen Sie einen Fingerabdruck manuell:

Suchen Sie den Fingerabdruck für Ihr Paket in Artifact Registry, wie unter Fingerabdruck eines Pakets in Ihrem Repository ansehen beschrieben.
Berechnen Sie den Fingerabdruck Ihres externen Pakets manuell:
1. Rufen Sie den kurzen Dateinamen und den individuellen SHA256-Hash jeder Datei in Ihrem Paket ab:
  1. Öffnen Sie in der Google Cloud Console die Seite Repositories:
    
    Zur Seite „Repositories“
  2. Wählen Sie Ihr Repository und dann das Image aus, das die Paketversion enthält, die Sie validieren möchten.
  3. Klicken Sie auf den Tab Dateien.
  4. Ermitteln Sie den kurzen Dateinamen und den SHA256-Hash jeder auf der Seite angezeigten Datei. Der kurze Dateiname ist der letzte String nach dem Speicherort der Datei. Der folgende Screenshot zeigt beispielsweise sechs Dateien für eine Version 5.0 eines Pakets in einem Maven-Repository. Jeder Dateiname beginnt mit my-app-5.0. Der Hashwert für jede Datei wird in der Spalte Hashes angezeigt:
2. Sortieren Sie die Dateien alphabetisch nach dem kurzen Dateinamen.
3. Kombinieren Sie für jeden sortierten Dateieintrag die Dateiinformationen in den folgenden gekürzten String. Fügen Sie zwischen dem Hash-Wert und dem Dateinamen zwei Leerzeichen ein und beenden Sie den String mit einem Nullbyte:
  
  HASH_VALUE FILE_NAME/0
4. Nehmen Sie jeden verkürzten String und fügen Sie sie zu einer vollständigen Sequenz zusammen, ohne Leerzeichen oder Zeichen zwischen den einzelnen Strings.
5. Berechnen Sie den SHA256-Hashwert der vollständigen Sequenz. Der endgültige SHA256-Hashwert ist der dirsum_sha256 Ihres externen Pakets.
Vergleichen Sie den manuell berechneten Fingerabdruck mit dem Fingerabdruck des Pakets in Ihrem Repository. Wenn beide Fingerabdrücke identisch sind, wurde die Instanz des Pakets in Ihrem Repository nicht geändert.