Utiliser des empreintes digitales pour valider les identités des versions de packages

Aperçu

Cette fonctionnalité est soumise aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service. Les fonctionnalités pré-DG sont disponibles "en l'état" et peuvent avoir une prise en charge limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Vous pouvez utiliser des empreintes d'artefact pour identifier de manière unique les packages dans les dépôts Artifact Registry.

Lorsque vous envoyez un package à un dépôt, Artifact Registry calcule une empreinte pour cette version du package. L'empreinte est une référence cryptographiquement immuable que vous pouvez utiliser pour vérifier que le package n'a pas été modifié lors de son déplacement entre Google Cloud des systèmes, tels que Compute Engine et Cloud Build. Une fois que vous avez récupéré l'empreinte de votre package, vous pouvez l'utiliser pour vous assurer qu'il est valide lors de certaines requêtes d'API Artifact Registry. Vous pouvez également valider les instances locales et de dépôt du même package en calculant manuellement l'empreinte locale et en la comparant à l'empreinte du dépôt.

Avant de commencer

1. Activez Artifact Registry, ce qui inclut l'activation de l'API Artifact Registry et l'installation de Google Cloud CLI.
2. (Facultatif) Configurez des valeurs par défaut pour les commandes gcloud.

Rôles requis

Pour obtenir les autorisations nécessaires pour afficher les empreintes de version de package dans les dépôts Artifact Registry, demandez à votre administrateur de vous accorder le rôle IAM Lecteur Artifact Registry (roles/artifactregistry.reader) sur le Google Cloud projet. Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

Récupérer l'empreinte d'une version de package dans votre dépôt

Les empreintes ont la structure suivante :

VERSION@DIRSUM_SHA256:HASH_VALUE

Pour récupérer l'empreinte d'une version de package dans un dépôt Artifact Registry, saisissez la commande suivante dans Google Cloud CLI :

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

Où :

• VERSION correspond à la version de votre package, par exemple 1.0543.
• REPOSITORY correspond au dépôt contenant le package que vous évaluez.
• LOCATION correspond à l'emplacement régional ou multirégional du dépôt. Vous pouvez ignorer cette option si vous définissez un emplacement par défaut.
• PACKAGE_NAME correspond au nom du package.

La réponse est semblable à ce qui suit :

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'

L'adresse complète de l'empreinte correspond à la version du package, suivie du type d'empreinte, puis de la valeur de hachage. Dans cet exemple, l'empreinte adresse est VERSION@DIRSUM_SHA256:7c07b910c6dd6df6984a5591d00ad0074fe24cd81145d2c681cdfda3b3d65a04.

Valider les empreintes en tant que références immuables dans l'API Artifact Registry

Certaines requêtes d'API Artifact Registry valident un package de votre dépôt si son empreinte est au format suivant :

VERSION@DIRSUM_SHA256:HASH_VALUE

Par exemple, vous souhaitez créer une pièce jointe sur un package dans votre dépôt. Dans la commande suivante, le package défini pour target est mis en forme de sorte qu'Artifact Registry valide également l'empreinte du package :

  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

Si l'empreinte fournie ne correspond pas à celle de la version actuelle, Artifact Registry rejette la requête d'API et affiche une erreur failed_precondition.

Les requêtes suivantes valident les empreintes fournies lorsqu'elles sont transmises à l'aide de bibliothèques d'API, de Google Cloud CLI et de curl :

• GetVersion
• UpdateVersion
• DeleteVersion
• ListFiles
• CreateAttachment
• ExportArtifact

Les requêtes suivantes valident les empreintes lorsqu'elles sont transmises à l'aide de bibliothèques d'API et de curl :

• ListAttachments

Vérifier que les instances locales et de dépôt d'un package sont identiques

Pour vérifier qu'un package n'a pas été modifié lors de son déplacement entre Google Cloud systèmes, calculez manuellement l'empreinte d' une instance de ce package en dehors de votre dépôt.

Pour calculer manuellement une empreinte, procédez comme suit :

1. Recherchez l'empreinte de votre package dans Artifact Registry, comme décrit dans Afficher l'empreinte d'un package dans votre dépôt.

2. Calculez manuellement l'empreinte de votre package externe :

   1. Obtenez le nom de fichier court et le hachage SHA256 individuel de chaque fichier de votre package :

      1. Ouvrez la page Dépôts dans la Google Cloud console :

         Ouvrir la page "Dépôts"

      2. Sélectionnez votre dépôt, puis l'image contenant la version du package que vous souhaitez valider.

      3. Cliquez sur l'onglet Fichiers.

      4. Identifiez le nom de fichier court et le hachage SHA256 de chaque fichier affiché sur la page. Le nom de fichier court est la chaîne finale qui suit l'emplacement du fichier. Par exemple, la capture d'écran suivante montre six fichiers pour une Version 5.0 d'un package dans un dépôt Maven. Chaque nom de fichier commence par my-app-5.0. La valeur de hachage de chaque fichier est affichée dans la colonne Hashes :

         

   2. Triez les fichiers par ordre alphabétique en fonction de leur nom de fichier court.

   3. Pour chaque entrée de fichier triée, combinez les informations du fichier dans la chaîne abrégée suivante, en ajoutant deux espaces entre la valeur de hachage et le nom de fichier, et en terminant par un octet nul :

      HASH_VALUE FILE_NAME/0

   4. Prenez chaque chaîne abrégée et combinez-les en une seule séquence complète, sans espace ni caractère entre chaque chaîne.

   5. Calculez la valeur de hachage SHA256 de la séquence complète. La valeur de hachage SHA256 finale correspond au dirsum_sha256 de votre package externe.

3. Comparez l'empreinte que vous avez calculée manuellement et celle du package dans votre dépôt. Si les deux empreintes sont identiques, l'instance du package dans votre dépôt n'a pas été modifiée.