指紋を使用してパッケージバージョンの ID を検証する

アーティファクトのフィンガープリントを使用すると、Artifact Registry リポジトリ内のパッケージを一意に識別できます。

パッケージをリポジトリに push すると、Artifact Registry はそのパッケージバージョンのフィンガープリントを計算します。フィンガープリントは、Compute Engine や Cloud Build などの Google Cloudシステム間で移動する際に、パッケージが変更されていないことを検証するために使用できる暗号的に不変の参照です。パッケージのフィンガープリントを取得したら、それを使用して、特定の Artifact Registry API リクエストでパッケージが有効であることを確認できます。ローカルフィンガープリントを手動で計算し、リポジトリ内のフィンガープリントと比較することで、同じパッケージのローカルインスタンスとリポジトリインスタンスを検証することもできます。

始める前に

Artifact Registry を有効にします。これには Artifact Registry API の有効化と、Google Cloud CLI のインストールが含まれます。
（省略可）gcloud コマンドのデフォルトを構成します。

必要なロール

Artifact Registry リポジトリでパッケージバージョンのフィンガープリントを表示するために必要な権限を取得するには、 Google Cloud プロジェクトに対する Artifact Registry 読み取り（roles/artifactregistry.reader）IAM ロールを付与するよう管理者に依頼してください。ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

リポジトリ内のパッケージバージョンのフィンガープリントを取得する

フィンガープリントの構造は次のとおりです。

VERSION@DIRSUM_SHA256:HASH_VALUE

Artifact Registry リポジトリ内のパッケージバージョンのフィンガープリントを取得するには、Google Cloud CLI で次のコマンドを入力します。

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

ここで

VERSION は、1.0543 などのパッケージのバージョンです。
REPOSITORY は、評価するパッケージを含むリポジトリです。
LOCATION は、リポジトリのリージョンまたはマルチリージョンのロケーションです。デフォルトのロケーションを設定すると、このフラグを省略できます。
PACKAGE_NAME はパッケージの名前です。

レスポンスは次のようになります。

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'

フィンガープリントの完全なアドレスは、パッケージバージョン、フィンガープリントタイプ、ハッシュ値の順に並べたものです。この例では、フィンガープリントアドレスは VERSION@DIRSUM_SHA256:7c07b910c6dd6df6984a5591d00ad0074fe24cd81145d2c681cdfda3b3d65a04 です。

Artifact Registry API で指紋を不変の参照として検証する

特定の Artifact Registry API リクエストは、パッケージのフィンガープリントが次の形式で指定されている場合、リポジトリからパッケージを検証します。

VERSION@DIRSUM_SHA256:HASH_VALUE

たとえば、リポジトリ内のパッケージに添付ファイルを作成する場合などです。次のコマンドでは、target に定義されたパッケージが、Artifact Registry がパッケージのフィンガープリントも検証するようにフォーマットされています。

  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

指定されたフィンガープリントが現在のバージョンのフィンガープリントと一致しない場合、Artifact Registry は API リクエストを拒否し、failed_precondition エラーを表示します。

次のリクエストは、API ライブラリ、Google Cloud CLI、curl を使用して渡されたときに、指定されたフィンガープリントを検証します。

次のリクエストは、API ライブラリと curl を使用して渡された場合に、指紋を検証します。

ListAttachments

パッケージのローカルインスタンスとリポジトリインスタンスが同じであることを検証する

Google Cloud システム間で移動する際にパッケージが変更されていないことを検証するには、リポジトリ外でそのパッケージのインスタンスのフィンガープリントを手動で計算します。

フィンガープリントを手動で計算する手順は次のとおりです。

リポジトリ内のパッケージのフィンガープリントを表示するの説明に沿って、Artifact Registry でパッケージのフィンガープリントを見つけます。
外部パッケージのフィンガープリントを手動で計算します。
1. パッケージ内の各ファイルの短いファイル名と個々の SHA256 ハッシュを取得します。
  1. Google Cloud コンソールで [リポジトリ] ページを開きます。
    
    [リポジトリ] ページを開く
  2. リポジトリを選択し、検証するパッケージバージョンを含むイメージを選択します。
  3. [ファイル] タブをクリックします。
  4. ページに表示されている各ファイルの短いファイル名と SHA256 ハッシュを特定します。短いファイル名は、ファイルの場所の後に続く最後の文字列です。たとえば、次のスクリーンショットは、Maven リポジトリ内のパッケージの Version 5.0 の 6 つのファイルを示しています。各ファイル名は my-app-5.0 で始まります。各ファイルのハッシュ値は、Hashes 列に表示されます。
2. 短いファイル名でファイルをアルファベット順に並べ替えます。
3. ソートされた各ファイルエントリについて、ファイル情報を次の短縮文字列に結合します。ハッシュ値とファイル名の間に 2 つのスペースを追加し、最後に null バイトを追加します。
  
  HASH_VALUE FILE_NAME/0
4. 短縮された各文字列を取得し、それらを 1 つの完全なシーケンスに結合します。各文字列の間にスペースや文字は入れません。
5. シーケンス全体の SHA256 ハッシュ値を計算します。最終的な SHA256 ハッシュ値は、外部パッケージの dirsum_sha256 です。
手動で計算したフィンガープリントと、リポジトリ内のパッケージのフィンガープリントを比較します。両方のフィンガープリントが同じ場合、リポジトリ内のパッケージのインスタンスは変更されていません。