b2sum と CLI によるダウンロードファイルの検証
チェックサムの検証では、実際に使用するファイルを対象にする必要があります。GNU b2sum --check はマニフェスト内のファイル名を検証します。マニフェストを my-app.bin.b2 という名前にしても、my-app.bin が検証対象になるわけではありません。この手順では、信頼できるチェックサムを作成し、サンプルリリースをダウンロード用ディレクトリにコピーして、スクリプトに渡された成果物そのものを Bash で検証します。
対応する BLAKE2 形式の使用
GNU b2sum は
BLAKE2b を使用し、デフォルトでは 512 ビットのダイジェストを 128 桁の16進数で出力します。BLAKE2s は別のバリアントです。b2sum --length=256 を選ぶと生成されるのは
BLAKE2s-256 ではなく BLAKE2b-256 であり、BLAKE2b-512 ダイジェストの前半とも異なります。アルゴリズムと長さは、配布元のチェックサムと一致している必要があります。RFC 7693 では、BLAKE2 が指定されたダイジェスト長をどのように計算に組み込むかを説明しています。
以下の例では、デフォルトの BLAKE2b-512 ダイジェストを使用します。チェックサムの照合により、信頼する参照値に対する変更を検出できます。ただし、配布元を特定したり、ダウンロードしたファイルを安全に実行できると保証したりするものではありません。
ローカルツールの確認
Bash、GNU coreutils(b2sum)、GNU diffutils(cmp)を備えた Linux を使用します。開始前に、これらを確認してください。
bash --version && b2sum --version && cmp --version
コマンドが見つからない場合は、ディストリビューションの bash、coreutils、または diffutils パッケージをインストールしてください。この手順は GNU coreutils 9.11 でテストしています。ローカルコピーを使って作成側と利用側の手順を示します。ホスト型 CI/CD サービスの設定や、ネットワーク経由のダウンロードは行いません。
サンプルリリースの作成
すべてのスニペットを同じ親ディレクトリから実行してください。サブシェルにより、ディレクトリの変更は各ブロック内だけに適用されます。セットアップでは b2sum-demo を作成し、既存のディレクトリは再利用しません。そのため、再実行しても以前の実験結果を上書きしません。
(
set -eu
mkdir -- b2sum-demo
cd -- b2sum-demo
mkdir -- release
printf 'example release\n' > 'release/my app.bin'
)
サンプルの成果物には、変更を確認しやすいようにテキストを格納しています。同じコマンドはバイナリファイルや空のファイルにも使えます。
単一ファイル用マニフェストの生成
作成側で、完成した成果物があるディレクトリからハッシュを計算します。
(
set -eu
set -o noclobber
cd -- b2sum-demo/release
b2sum --binary -- './my app.bin' > './my app.bin.b2'
)
この出力は変更せずに保持してください。ダイジェスト、スペース、バイナリモードのマーカー
*、相対ファイル名 ./my app.bin、末尾の改行が含まれます。GNU のドキュメントに、このチェックサムレコード形式の説明があります。./ は記録されるファイル名の一部であり、先頭のハイフンがオプションとして扱われることも防ぎます。
noclobber は既存のマニフェストの置き換えを拒否します。シェルが先に出力ファイルを開くため、ハッシュ計算コマンドが失敗すると、新しいサイドカーファイルが不完全な状態で残ることがあります。その失敗した出力は公開しないでください。チェックサムは信頼できるリリースから生成してください。検証を通すためだけに、疑わしいダウンロードファイルから生成してはいけません。
リリースのコピーと検証
ダウンロードの代わりに、両方のファイルを新しいディレクトリにコピーします。このブロックも、既存のコピー先ディレクトリの再利用を拒否します。
(
set -eu
mkdir -- b2sum-demo/downloads
cp -- 'b2sum-demo/release/my app.bin' 'b2sum-demo/release/my app.bin.b2' b2sum-demo/downloads/
)
このマニフェストでは、成果物があるディレクトリがルートになります。標準の検証ツールを使用する前に、そのディレクトリに移動してください。
(
cd -- b2sum-demo/downloads &&
b2sum --check --strict -- './my app.bin.b2'
)
C ロケールの coreutils 9.11 では、次の出力が得られます。ファイル名の引用符の付け方は、バージョンやロケールによって異なる場合があります。
'./my app.bin': OK
マニフェスト内の相対ファイル名は、マニフェストの場所ではなく、検証ツールの作業ディレクトリを基準に解決されます。親ディレクトリから b2sum --check b2sum-demo/downloads/my\ app.bin.b2 を実行すると、親ディレクトリ内の ./my app.bin を探します。成果物とマニフェストを一緒に移動した場合も、移動先のディレクトリから検証を実行すれば動作します。
--strict オプションは、不正な形式のレコードを失敗として扱います。ただし、マニフェストが意図した成果物を指定しているかどうかは確認しません。other.bin の完全に有効なレコードは、my app.bin が破損していたり存在しなかったりしても検証に成功し得ます。呼び出し元が特定の単一ファイルを指定する場合は、次のスクリプトを使用してください。
整合性検証の自動化
次の内容を b2sum-demo/verify-integrity.sh として保存してください。このスクリプトは成果物のパスを一つ受け取り、隣接する .b2 ファイルを読み込みます。受け付けるマニフェストの仕様は意図的に限定しています。成果物のベース名とデフォルトのダイジェスト長を使用し、b2sum --binary -- './filename' が生成した単一のレコードと厳密に一致する必要があります。タグ付き出力、追加のレコード、変更された空白、異なるパス表記は拒否します。
#!/usr/bin/env bash
set -euo pipefail
if (( $# != 1 )) || [[ -z $1 ]]; then
printf 'Usage: %s <artifact>\n' "$0" >&2
exit 2
fi
artifact=$1
[[ $artifact == /* ]] || artifact="./$artifact"
if [[ ! -f $artifact || ! -f $artifact.b2 ]]; then
printf 'Artifact or manifest missing: %s\n' "$1" >&2
exit 1
fi
cd -P -- "${artifact%/*}/"
name=${artifact##*/}
if b2sum --binary -- "./$name" | cmp --silent -- "./$name.b2" -; then
printf 'Verified: %s\n' "$1"
else
printf 'Verification failed: %s\n' "$1" >&2
exit 1
fi
このスクリプトは指定されたファイルのハッシュを計算し、ファイル名を含む新しいレコード全体を、信頼できるマニフェストと比較します。cmp はバイト列が一致した場合にのみ成功を返します。Bash の
pipefail により、ハッシュ計算プロセスの失敗もパイプラインの失敗になります。ファイル名に含まれるスペースや先頭のハイフンにも対応しています。
スクリプト自体が成果物のディレクトリに移動するため、呼び出し元は別のディレクトリから相対パスまたは絶対パスを指定できます。cd -P による物理ディレクトリの解決では、シンボリックリンクの後に .. が続くパスの意味が保たれます。成果物にもマニフェストにも書き込みません。検証からその後の使用まで、両方を変更せずに保持してください。このスクリプトは、同時に行われる変更を防ぐためのファイルロックは行いません。
検証失敗時の後続処理の停止
Bash 経由で検証スクリプトを実行し、その終了ステータスに応じて次のコマンドを実行します。
bash b2sum-demo/verify-integrity.sh 'b2sum-demo/downloads/my app.bin' &&
printf 'Ready to use the verified artifact\n'
成功すると、次の内容を出力します。
Verified: b2sum-demo/downloads/my app.bin
Ready to use the verified artifact
失敗を試すには、破棄してよいダウンロード済みのコピーだけを変更してください。
printf 'changed\n' >> 'b2sum-demo/downloads/my app.bin' &&
bash b2sum-demo/verify-integrity.sh 'b2sum-demo/downloads/my app.bin'
この場合、標準エラーに Verification failed: b2sum-demo/downloads/my app.bin を出力し、ステータス 1 で終了します。CI/CD ジョブでも同様に、成果物を使用する処理やデプロイ処理は、検証の成功を実行条件にする必要があります。後続のシェルコマンドの成功によって、この失敗が隠されないようにしてください。
よくある問題への対処
b2sum --checkが受け付けるマニフェストをスクリプトが拒否する: ファイル名と形式を確認してください。このスクリプトには、./basenameを含む単一のバイナリモードレコードが、末尾の改行まで必要です。配布元の複数ファイル用マニフェストを使用する場合は、標準の検証ツールを実行する前に、文書化されたディレクトリ構成に従い、対象となるファイルを確認してください。- バイト列が異なる: 意図したリリースをダウンロードしたか確認してください。信頼できる配布元から再ダウンロードし、不一致が繰り返される場合は調査してください。テキストの改行コードが変わった場合も、ハッシュは変化します。
- ファイルがない、または読み取れない: 成果物のパスと
.b2サイドカーファイルの両方に加え、ディレクトリの権限を確認してください。空の成果物はチェックサムが一致すれば有効ですが、空のマニフェストは無効です。 - コマンドが見つからない: 検証スクリプトの実行パスには、GNU
b2sumとcmpの両方が必要です。ハッシュ計算または比較に失敗すると、ゼロ以外のステータスを返します。
期待するチェックサムの信頼性の維持
期待するチェックサムは信頼できるリリース配布経路から取得するか、配布元の身元を独立した方法で確認した鍵を使用して、署名付きマニフェストを検証してください。成果物とチェックサムの両方を置き換えられる攻撃者は、この検証を通過させられます。侵害された同じ場所から両方をダウンロードしても、真正性は保証されません。
このローカルコピーの例では、転送後の整合性検証を示しています。ダウンロードしたバイト列から新しいチェックサムを生成しても、届いた内容を表すだけです。作成側の信頼できるチェックサムを参照値として保持し、成果物を使用する前に検証してください。
