Usa huellas digitales para verificar las identidades de las versiones de paquetes

Puedes usar huellas digitales de artefactos para identificar de forma única los paquetes en los repositorios de Artifact Registry.

Cuando envías un paquete a un repositorio, Artifact Registry calcula una huella digital para esa versión del paquete. La huella digital es una referencia criptográfica inmutable que puedes usar para validar que el paquete no se modificó cuando se trasladó entre sistemas de Google Cloud, como Compute Engine y Cloud Build. Después de recuperar la huella digital de tu paquete, puedes usarla para asegurarte de que sea válida durante ciertas solicitudes a la API de Artifact Registry. También puedes validar instancias locales y de repositorio del mismo paquete calculando manualmente la huella digital local y comparándola con la huella digital del repositorio.

Antes de comenzar

Habilita Artifact Registry, incluida la habilitación de la API de Artifact Registry y la instalación de Google Cloud CLI.
(Opcional) Configura valores predeterminados para los comandos de gcloud.

Roles obligatorios

Para obtener los permisos que necesitas para ver las huellas digitales de las versiones de paquetes en los repositorios de Artifact Registry, pídele a tu administrador que te otorgue el rol de IAM Lector de Artifact Registry (roles/artifactregistry.reader) en el proyecto Google Cloud . Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Recupera la huella digital de una versión del paquete en tu repositorio

Las huellas digitales tienen la siguiente estructura:

VERSION@DIRSUM_SHA256:HASH_VALUE

Para recuperar la huella digital de una versión de paquete en un repositorio de Artifact Registry, ingresa lo siguiente en Google Cloud CLI:

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

Donde:

VERSION es la versión de tu paquete, como 1.0543.
REPOSITORY es el repositorio que contiene el paquete que estás evaluando.
LOCATION es la ubicación regional o multirregional del repositorio. Puedes omitir esta marca si estableces una ubicación predeterminada.
PACKAGE_NAME es el nombre del paquete.

La respuesta es similar a la que se muestra a continuación:

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'

La dirección completa de la huella digital es la versión del paquete seguida del tipo de huella digital y, luego, el valor hash. En este ejemplo, la dirección de huella digital es VERSION@DIRSUM_SHA256:7c07b910c6dd6df6984a5591d00ad0074fe24cd81145d2c681cdfda3b3d65a04.

Valida huellas digitales como referencias inmutables en la API de Artifact Registry

Algunas solicitudes a la API de Artifact Registry validarán un paquete de tu repositorio si la huella digital de ese paquete tiene el siguiente formato:

VERSION@DIRSUM_SHA256:HASH_VALUE

Por ejemplo, deseas crear un adjunto en un paquete de tu repositorio. En el siguiente comando, el paquete definido para target se formatea de modo que Artifact Registry también valide la huella digital del paquete:

  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 la huella digital proporcionada no coincide con la de la versión actual, Artifact Registry rechaza la solicitud a la API y muestra un error failed_precondition.

Las siguientes solicitudes validarán las huellas digitales proporcionadas cuando se pasen a través de las bibliotecas de la API, Google Cloud CLI y curl:

Las siguientes solicitudes validarán las huellas digitales cuando se pasen con las bibliotecas de la API y curl:

ListAttachments

Valida que las instancias locales y del repositorio de un paquete sean las mismas

Para validar que un paquete no se haya modificado mientras se mueve entre los sistemasGoogle Cloud , calcula manualmente la huella digital de una instancia de ese paquete fuera de tu repositorio.

Para calcular manualmente una huella digital, haz lo siguiente:

Busca la huella digital de tu paquete en Artifact Registry como se describe en Cómo ver la huella digital de un paquete en tu repositorio.
Calcula manualmente la huella digital de tu paquete externo:
1. Obtén el nombre corto del archivo y el hash SHA256 individual de cada archivo de tu paquete:
  1. Abre la página Repositorios en la consola de Google Cloud :
    
    Abrir la página repositorios
  2. Selecciona tu repositorio y, luego, la imagen que contiene la versión del paquete que deseas validar.
  3. Haz clic en la pestaña Archivos.
  4. Identifica el nombre corto del archivo y el hash SHA256 de cada archivo que se muestra en la página. El nombre de archivo corto es la cadena final que sigue a la ubicación del archivo. Por ejemplo, en la siguiente captura de pantalla, se muestran seis archivos para un Version 5.0 de un paquete en un repositorio de Maven. Cada nombre de archivo comienza con my-app-5.0. El valor hash de cada archivo se muestra en la columna Hashes:
2. Ordena los archivos alfabéticamente por nombre corto.
3. Para cada entrada de archivo ordenada, combina la información del archivo en la siguiente cadena abreviada, agrega dos espacios entre el valor hash y el nombre del archivo, y termina con un byte nulo:
  
  HASH_VALUE FILE_NAME/0
4. Toma cada cadena abreviada y combínalas en una secuencia completa, sin espacios ni caracteres entre cada cadena.
5. Calcula el valor de hash SHA256 de la secuencia completa. El valor final del hash SHA256 es el dirsum_sha256 de tu paquete externo.
Compara la huella digital que calculaste manualmente con la del paquete en tu repositorio. Si ambas huellas digitales son iguales, significa que no se modificó la instancia del paquete en tu repositorio.