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

É possível usar impressões digitais de artefatos para identificar pacotes de maneira exclusiva nos 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 Google Cloud sistemas, como o Compute Engine e o Cloud Build. Depois de recuperar a impressão digital do pacote, você poderá usá-la para garantir que o pacote seja válido durante determinadas solicitações de 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

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

Funções exigidas

Para receber as permissões necessárias para visualizar impressões digitais de versões de pacotes nos 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 Google Cloud projeto. 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 personalizados papéis ou outros predefinidos papéis.

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

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

VERSION@DIRSUM_SHA256:HASH_VALUE

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

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

Em que:

  • VERSION é a versão do pacote, como 1.0543.
  • REPOSITORY é o repositório que contém o pacote que você está avaliando.
  • LOCATION é o local regional ou multirregional location 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 da impressão digital é VERSION@DIRSUM_SHA256:7c07b910c6dd6df6984a5591d00ad0074fe24cd81145d2c681cdfda3b3d65a04.

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

Determinadas solicitações da API Artifact Registry validam um pacote do 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 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 à impressão digital da versão atual, o Artifact Registry rejeitará a solicitação de API e mostrará um erro failed_precondition.

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

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

Validar se as instâncias locais e de repositório de um pacote são as mesmas

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

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

  1. Encontre a impressão digital do pacote no Artifact Registry, conforme descrito em Ver a impressão digital de um pacote no repositório.

  2. Calcule manualmente a impressão digital do pacote externo:

    1. Receba o nome abreviado do arquivo e o hash SHA256 individual de cada arquivo no pacote:

      1. Abra a página Repositórios no Google Cloud console:

        Abrir a página Repositórios

      2. Selecione o 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 do arquivo 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 uma 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:

        Uma amostra da guia **Arquivos** para a versão 5.0 de um pacote Maven.

    2. Classifique os arquivos em ordem alfabética pelo nome abreviado do arquivo.

    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 cada string.

    5. Calcule o valor de hash SHA256 da sequência completa. O valor final do hash SHA256 é o dirsum_sha256 do pacote externo.

  3. Compare a impressão digital calculada manualmente e a impressão digital do pacote no repositório. Se as duas impressões digitais forem iguais, a instância do pacote no repositório não terá sido modificada.