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

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

Lorsque vous transférez un package vers un dépôt, Artifact Registry calcule une empreinte digitale pour cette version du package. L'empreinte digitale est une référence cryptographiquement immuable que vous pouvez utiliser pour vérifier que le package n'a pas été modifié lors du transfert entre les systèmes Google Cloud, 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 de l'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

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

Rôles requis

Pour obtenir les autorisations nécessaires pour afficher les empreintes digitales des versions de packages 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 projet Google Cloud . Pour en savoir plus sur l'attribution de rôles, consultez la page 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 digitale 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 digitale 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 est le dépôt contenant le package que vous évaluez.
LOCATION est 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 est le 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 digitale correspond à la version du package, suivie du type d'empreinte digitale, puis de la valeur du hachage. Dans cet exemple, l'adresse de l'empreinte digitale est VERSION@DIRSUM_SHA256:7c07b910c6dd6df6984a5591d00ad0074fe24cd81145d2c681cdfda3b3d65a04.

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

Certaines requêtes de l'API Artifact Registry valident un package de votre dépôt si l'empreinte de ce package est formatée comme suit :

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 digitale 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 API et affiche une erreur failed_precondition.

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

Les requêtes suivantes valideront les empreintes digitales lorsqu'elles seront transmises à l'aide des bibliothèques d'API et de curl :

ListAttachments

Valider 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 du transfert entre les systèmesGoogle Cloud , calculez manuellement l'empreinte digitale d'une instance de ce package en dehors de votre dépôt.

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

Recherchez l'empreinte digitale de votre package dans Artifact Registry, comme décrit dans Afficher l'empreinte digitale d'un package dans votre dépôt.
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 console Google Cloud :
    
    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 dernière chaîne après l'emplacement du fichier. Par exemple, la capture d'écran suivante montre six fichiers pour un 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 indiquée dans la colonne Hashes :
2. Triez les fichiers par ordre alphabétique en fonction de leur nom court.
3. Pour chaque entrée de fichier triée, combinez les informations sur le fichier dans la chaîne abrégée suivante, en ajoutant deux espaces entre la valeur de hachage et le nom du fichier, et en terminant par un octet nul :
  
  HASH_VALUE FILE_NAME/0
4. Prenez chaque chaîne raccourcie et combinez-les en une seule séquence complète, sans espaces ni caractères entre chaque chaîne.
5. Calculez la valeur de hachage SHA256 de la séquence complète. La valeur de hachage SHA256 finale correspond à dirsum_sha256 pour votre package externe.
Comparez l'empreinte digitale que vous avez calculée manuellement à celle du package dans votre dépôt. Si les deux empreintes digitales sont identiques, cela signifie que l'instance du package dans votre dépôt n'a pas été modifiée.