Utilizzare le impronte per verificare le identità delle versioni dei pacchetti

Puoi utilizzare le impronte degli artefatti per identificare in modo univoco i pacchetti nei repository Artifact Registry.

Quando esegui il push di un pacchetto in un repository, Artifact Registry calcola un'impronta per quella versione del pacchetto. L'impronta è un riferimento crittograficamente immutabile che puoi utilizzare per verificare che il pacchetto non sia stato modificato durante lo spostamento tra sistemi, come Compute Engine e Cloud Build. Google CloudDopo aver recuperato l'impronta del pacchetto, puoi utilizzarla per assicurarti che il pacchetto sia valido durante determinate richieste API Artifact Registry. Puoi anche convalidare le istanze locali e del repository dello stesso pacchetto calcolando manualmente l'impronta locale e confrontandola con l'impronta nel repository.

Prima di iniziare

Abilita Artifact Registry, inclusa l'abilitazione dell'API Artifact Registry e l'installazione di Google Cloud CLI.
(Facoltativo) Configura le impostazioni predefinite per i comandi gcloud.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per visualizzare le impronte delle versioni dei pacchetti nei repository Artifact Registry, chiedi all'amministratore di concederti il ruolo IAM Artifact Registry Reader (roles/artifactregistry.reader) sul progetto Google Cloud . Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Recuperare l'impronta di una versione del pacchetto nel repository

Le impronte hanno la seguente struttura:

VERSION@DIRSUM_SHA256:HASH_VALUE

Per recuperare l'impronta di una versione del pacchetto in un repository Artifact Registry, inserisci quanto segue in Google Cloud CLI:

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

Dove:

VERSION è la versione del pacchetto, ad esempio 1.0543.
REPOSITORY è il repository contenente il pacchetto che stai valutando
LOCATION è la posizione regionale o multiregionale del repository. Puoi omettere questo flag se imposti una posizione predefinita.
PACKAGE_NAME è il nome del pacchetto.

La risposta è simile alla seguente:

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'indirizzo completo dell'impronta è la versione del pacchetto seguita dal tipo di impronta e poi dal valore hash. In questo esempio, l'indirizzo dell'impronta è VERSION@DIRSUM_SHA256:7c07b910c6dd6df6984a5591d00ad0074fe24cd81145d2c681cdfda3b3d65a04.

Convalida le impronte come riferimenti immutabili nell'API Artifact Registry

Determinate richieste API Artifact Registry convalidano un pacchetto dal tuo repository se l'impronta di quel pacchetto è formattata nel seguente modo:

VERSION@DIRSUM_SHA256:HASH_VALUE

Ad esempio, vuoi creare un allegato in un pacchetto nel tuo repository. Nel comando seguente, il pacchetto definito per target è formattato in modo che Artifact Registry convalidi anche l'impronta del pacchetto:

  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 l'impronta fornita non corrisponde a quella della versione attuale, Artifact Registry rifiuta la richiesta API e mostra un errore failed_precondition.

Le seguenti richieste convalidano le impronte fornite quando vengono trasmesse utilizzando le librerie API, Google Cloud CLI e curl:

Le seguenti richieste convalidano le impronte quando vengono trasmesse utilizzando le librerie API e curl:

ListAttachments

Verifica che le istanze locali e del repository di un pacchetto siano uguali

Per verificare che un pacchetto non sia stato modificato durante lo spostamento tra i sistemiGoogle Cloud , calcola manualmente l'impronta di un'istanza del pacchetto al di fuori del repository.

Per calcolare manualmente un'impronta:

Trova l'impronta del tuo pacchetto in Artifact Registry come descritto in Visualizzare l'impronta di un pacchetto nel repository.
Calcola manualmente l'impronta del pacchetto esterno:
1. Ottieni il nome breve del file e l'hash SHA256 individuale di ogni file nel tuo pacchetto:
  1. Apri la pagina Repository nella console Google Cloud :
    
    Apri la pagina Repositori
  2. Seleziona il repository, quindi seleziona l'immagine che contiene la versione del pacchetto che vuoi convalidare.
  3. Fai clic sulla scheda File.
  4. Identifica il nome breve del file e l'hash SHA256 di ogni file mostrato nella pagina. Il nome breve del file è la stringa finale che segue la posizione del file. Ad esempio, lo screenshot seguente mostra sei file per un Version 5.0 di un pacchetto in un repository Maven. Ogni nome file inizia con my-app-5.0. Il valore hash di ogni file viene visualizzato nella colonna Hashes:
2. Ordina i file alfabeticamente in base al nome breve.
3. Per ogni voce di file ordinata, combina le informazioni sul file nella seguente stringa abbreviata, aggiungendo due spazi tra il valore hash e il nome del file e terminando con un byte null:
  
  HASH_VALUE FILE_NAME/0
4. Prendi ogni stringa abbreviata e combinale in una sequenza completa, senza spazi o caratteri tra le stringhe.
5. Calcola il valore hash SHA256 dell'intera sequenza. Il valore finale dell'hash SHA256 è il dirsum_sha256 del tuo pacchetto esterno.
Confronta l'impronta calcolata manualmente con l'impronta del pacchetto nel tuo repository. Se entrambe le impronte sono uguali, l'istanza del pacchetto nel repository non è stata modificata.