Usar impressões digitais para verificar identidades de versões de pacotes

É possível usar impressões digitais de artefatos para identificar exclusivamente pacotes em repositórios do Artifact Registry.

Quando você envia um pacote para um repositório, o Artifact Registry calcula uma impressão digital para essa versão do pacote. A impressão digital é uma referência criptograficamente imutável que pode ser usada para validar se o pacote não foi modificado ao ser movido entre sistemas Google Cloud, como o Compute Engine e o Cloud Build. Depois de recuperar a impressão digital do pacote, use-a para garantir que ele seja válido durante determinadas solicitações da API Artifact Registry. Também é possível validar instâncias locais e de repositório do mesmo pacote calculando manualmente a impressão digital local e comparando-a com a impressão digital no repositório.

Antes de começar

Ative o Artifact Registry, incluindo a ativação da API do Artifact Registry e a instalação do Google Cloud CLI.
(Opcional) Configure padrões para comandos gcloud.

Funções exigidas

Para receber as permissões necessárias para ver impressões digitais de versões de pacotes em repositórios do Artifact Registry, peça ao administrador para conceder a você o papel do IAM de Leitor do Artifact Registry (roles/artifactregistry.reader) no projeto Google Cloud . Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Recuperar a impressão digital de uma versão do pacote no seu repositório

As impressões digitais têm a seguinte estrutura:

VERSION@DIRSUM_SHA256:HASH_VALUE

Para extrair a impressão digital de uma versão de pacote em um repositório do Artifact Registry, insira o seguinte na CLI do Google Cloud:

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

Em que:

VERSION é a versão do seu pacote, como 1.0543.
REPOSITORY é o repositório que contém o pacote que você está avaliando.
LOCATION é o local regional ou multirregional do repositório. É possível omitir essa flag se você definir um local padrão.
PACKAGE_NAME é o nome do pacote.

A resposta será assim:

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'

O endereço completo da impressão digital é a versão do pacote seguida pelo tipo de impressão digital e pelo valor de hash. Neste exemplo, o endereço de impressão digital é VERSION@DIRSUM_SHA256:7c07b910c6dd6df6984a5591d00ad0074fe24cd81145d2c681cdfda3b3d65a04.

Validar impressões digitais como referências imutáveis na API Artifact Registry

Algumas solicitações da API Artifact Registry validam um pacote do seu repositório se a impressão digital desse pacote estiver formatada da seguinte maneira:

VERSION@DIRSUM_SHA256:HASH_VALUE

Por exemplo, você quer criar um anexo em um pacote no seu repositório. No comando a seguir, o pacote definido para target é formatado para que o Artifact Registry também valide a impressão digital do pacote:

  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

Se a impressão digital fornecida não corresponder à da versão atual, o Artifact Registry vai rejeitar a solicitação de API e mostrar um erro failed_precondition.

As solicitações a seguir vão validar as impressões digitais fornecidas quando transmitidas usando bibliotecas de API, a CLI do Google Cloud e curl:

As solicitações a seguir vão validar impressões digitais quando transmitidas usando bibliotecas de API e curl:

ListAttachments

Validar se as instâncias local e do repositório de um pacote são iguais

Para validar se um pacote não foi modificado ao se mover entre sistemasGoogle Cloud , calcule manualmente a impressão digital de uma instância desse pacote fora do seu repositório.

Para calcular manualmente uma impressão digital, faça o seguinte:

Encontre a impressão digital do seu pacote no Artifact Registry, conforme descrito em Ver a impressão digital de um pacote no repositório.
Calcule manualmente a impressão digital do seu pacote externo:
1. Receba o nome abreviado e o hash SHA256 individual de cada arquivo no seu pacote:
  1. Abra a página Repositórios no console do Google Cloud :
    
    Abrir a página Repositórios
  2. Selecione seu repositório e a imagem que contém a versão do pacote que você quer validar.
  3. Clique na guia Arquivos.
  4. Identifique o nome abreviado e o hash SHA256 de cada arquivo mostrado na página. O nome abreviado do arquivo é a string final após o local do arquivo. Por exemplo, a captura de tela a seguir mostra seis arquivos para um Version 5.0 de um pacote em um repositório Maven. Cada nome de arquivo começa com my-app-5.0. O valor de hash de cada arquivo é mostrado na coluna Hashes:
2. Classifique os arquivos em ordem alfabética pelo nome curto.
3. Para cada entrada de arquivo classificada, combine as informações do arquivo na seguinte string abreviada, adicionando dois espaços entre o valor de hash e o nome do arquivo e terminando com um byte nulo:
  
  HASH_VALUE FILE_NAME/0
4. Pegue cada string abreviada e combine-as em uma sequência completa, sem espaços ou caracteres entre elas.
5. Calcule o valor de hash SHA256 da sequência completa. O valor final do hash SHA256 é o dirsum_sha256 do seu pacote externo.
Compare a impressão digital calculada manualmente com a do pacote no seu repositório. Se as duas impressões digitais forem iguais, a instância do pacote no seu repositório não foi modificada.