b2sum と GNU Parallel によるアーティファクトマニフェストの検証
GNU b2sum で完成済みのアーティファクト一式を記録し、期待値を再生成せずに検証します。この手順では、小さなバックアップディレクトリのハッシュを並列計算し、すべての計算が成功した場合にのみマニフェストを置き換えます。また、検証の失敗をシェルや CI ジョブに伝えます。
ダイジェストだけでは、ファイルの作成者は確認できません。ファイルとチェックサムの両方を信頼できないソースからダウンロードするのではなく、認証されたリリースや署名付きマニフェストなど、信頼できる経路から期待するチェックサムを取得してください。
対応するチェックサム形式の選択
GNU b2sum は、デフォルトで BLAKE2b-512 を使用し、128 桁の16進数で出力します。期待値と同じアルゴリズムとダイジェスト長を使用してください。BLAKE2s と SHA-256 は異なる形式です。配布元が SHA-256 を提供している場合は、ダウンロードしたファイルから独自の BLAKE2 基準値を作るのではなく、sha256sum で検証してください。
このデモでは、既知のファイルからローカルの基準値を作成します。リリースのワークフローでは、アーティファクトの完成後に、信頼できる生成側でマニフェストを作成し、その出所と内容を保護してください。アーティファクトと期待値の両方を置き換えられる人は、検証を通過させられます。
Linux の前提条件の確認
Bash、GNU coreutils、GNU findutils、GNU Parallel、Python 3 を備えた Linux を使用します。Debian または Ubuntu では、対応するパッケージは
bash、coreutils、findutils、parallel、python3 です。GNU Parallel は別途インストールする必要があります。parallel という名前の別のコマンドでは代用できません。デモ用ディレクトリを作成する前に、利用可能か確認してください。
bash --version && b2sum --version && find --version && parallel --version && python3 --version
この例は Bash 5.3.15、coreutils 9.11、findutils 4.11.0、GNU Parallel 20240222、Python 3.14.7 でテストしています。Python はデモファイルの作成にのみ使用し、サードパーティーのパッケージは不要です。これはローカルの Linux 向けワークフローであり、macOS や Windows 向けの手順ではありません。
小規模なアーティファクト一式の作成
自分で管理するディレクトリから始めてください。このコマンドは新しいディレクトリに移動し、同名のディレクトリがすでにある場合は再利用を拒否します。
mkdir -- integrity-demo && cd -- integrity-demo
以降のファイルとコマンドは integrity-demo 内に配置して実行してください。次の内容を make-fixture.py として保存します。
from pathlib import Path
root = Path('backups')
root.mkdir()
(root / 'archive').mkdir()
samples = {
'app.tar': b'first release\n',
'archive/app.tar': b'other release\n',
'empty.tar': b'',
'-draft.tar': bytes([0, 255, 16, 10]),
'café copy.tar': b'Unicode name\n',
'line\nbreak.tar': b'newline name\n',
}
for name, content in samples.items():
(root / name).write_bytes(content)
一度実行します。
python3 -I make-fixture.py
この六つの小さなファイルで、空の内容、バイナリの内容、重複するベース名、空白、Unicode、ファイル名に含まれる改行を試します。これらは .tar という接尾辞を付けたサンプルデータであり、実際の tar アーカイブではありません。ジェネレーターは既存の backups ディレクトリを拒否します。セットアップが中断された場合は、作成途中のディレクトリを確認し、未使用のディレクトリで新しいデモを始めてください。ジェネレーターを再実行しても、以前のファイルは修復も上書きもされません。
完全なマニフェストの生成
次の内容を hash-backups.sh として保存してください。シェルに貼り付けるのではなく、保存した Bash スクリプトとして実行します。
#!/usr/bin/env bash
set -euo pipefail
export LC_ALL=C
umask 077
if (( $# != 1 )) || [[ -z $1 ]]; then
printf 'Usage: bash hash-backups.sh BACKUP_DIR\n' >&2
exit 2
fi
backupDir=$1
if [[ $backupDir != /* ]]; then
backupDir=./$backupDir
fi
if [[ ! -d $backupDir ]]; then
printf 'Not a directory: %s\n' "$backupDir" >&2
exit 2
fi
tempDir=$(mktemp -d .checksums.XXXXXX)
trap 'rm -rf -- "$tempDir"' EXIT
find "$backupDir" -type f -name '*.tar' -print0 > "$tempDir/files.nul"
if [[ ! -s $tempDir/files.nul ]]; then
printf 'No .tar files selected in %s\n' "$backupDir" >&2
exit 1
fi
sort -z "$tempDir/files.nul" |
parallel --plain --will-cite --tmpdir "$tempDir" -0 --jobs 4 \
--keep-order --halt now,fail=1 b2sum -- {} > "$tempDir/checksums.b2"
test -s "$tempDir/checksums.b2"
mv -fT -- "$tempDir/checksums.b2" checksums.b2
生成側のスクリプトを実行します。
bash hash-backups.sh backups
このスクリプトは、シンボリックリンクのエントリーをたどらずに、小文字の .tar という接尾辞を持つ通常ファイルを再帰的に選択します。GNU Parallel は最大四つのハッシュ計算ジョブを実行し、出力をジョブごとにまとめ、ソート済みの入力順序を維持します。--plain オプションは、個人のプロファイルと PARALLEL の設定を無視します。一方、--halt now,fail=1 はハッシュ計算の失敗時に処理を停止します。選択結果が空の場合、ディレクトリの走査に失敗した場合、またはハッシュ計算に失敗した場合は、checksums.b2 を置き換える前に非ゼロの終了ステータスで終了します。
一時ディレクトリは保存先と同じ親ディレクトリ内にあるため、最後の mv は同じファイルシステム上で名前を変更し、完成したマニフェストを公開します。再実行が成功すると、以前のマニフェストを置き換えます。失敗した場合は以前のマニフェストをそのまま保持し、一時ファイルを削除します。生成側のスクリプトは一度に一つだけ実行し、走査、ハッシュ計算、検証の間はアーティファクトのディレクトリを変更しないでください。これはファイルシステムのスナップショットではありません。
記録されたファイルの検証
同じ integrity-demo ディレクトリから、checksums.b2 は変更せずに検証側を実行します。
b2sum --check --strict --quiet checksums.b2 && printf 'All recorded files match checksums.b2\n'
All recorded files match checksums.b2
--check は、マニフェスト内のパスを読み取ります。パスにはディレクトリが含まれているため、二つの app.tar ファイルを区別できます。相対パスはマニフェストのディレクトリではなく、現在のディレクトリを基準に解決されます。転送した一式を検証する場合は、ディレクトリ構造全体をマニフェストとともにコピーしてください。
find -print0 と parallel -0 はファイル名の境界を保持します。マニフェスト自体は GNU のエスケープ付き改行区切り形式を使用し、ファイル名に含まれる改行やバックスラッシュを表現できます。レコードを空白で分割したり、b2sum --zero を追加したりしないでください。NUL 区切りのチェックサム出力は、--check ではサポートされていません。
次に、対象のアーティファクトだけを変更し、検証手順を繰り返します。
printf 'changed release\n' >> backups/app.tar &&
b2sum --check --strict --quiet checksums.b2
コマンドは非ゼロの終了ステータスで終了し、./backups/app.tar のチェックサム不一致を報告します。backups/archive/app.tar がまだ存在していても同様です。記録されたファイルが欠落している場合や読み取れない場合も失敗します。さらに、--strict により、形式が不正なチェックサムレコードも失敗になります。再検証の前にアーティファクトを修正するか、信頼できるコピーから復元してください。マニフェストを再生成すると、変更後のバイト列を受け入れることになります。
検証の対象は記録されたファイルです。新しく追加されたファイルの検出、アーカイブ構造の確認、アーティファクトの作成者の確認は行いません。基準値を変更する場合は、追加ファイルを検証済みと見なすのではなく、レビューを経て生成側のスクリプトを新たに実行してください。
CI への失敗の伝達
検証コマンドを verify-backups.sh として保存し、終了ステータスが呼び出し元に伝わるようにします。
#!/usr/bin/env bash
set -euo pipefail
b2sum --check --strict checksums.b2
信頼できるマニフェストと、そこに記録されたディレクトリ構造を含むディレクトリから実行します。
bash verify-backups.sh
CI ジョブでも、保護されたマニフェストをチェックアウトし、記録されたパスにアーティファクトを配置した後、同じ呼び出し方を使用できます。検証ジョブではマニフェストを生成しないでください。正当な基準値の更新は別途レビューし、アーティファクトだけでなくマニフェストへの書き込み権限も保護してください。検証の終了ステータスを保持せずに出力を別のコマンドへパイプすると、不一致が見えなくなるおそれがあります。
実際のワークロードでの性能測定
性能はファイルサイズ、ストレージ、キャッシュ、CPU 命令、実装によって異なります。次のコマンドは、デモファイルの処理時間を測定する方法を示しています。有意義な測定を行うには、backups/app.tar を、完成済みの代表的なファイルに置き換えてください。
time b2sum -- backups/app.tar > /dev/null &&
time sha256sum -- backups/app.tar > /dev/null
この小さなデモファイルでは、有用な速度比較はできません。BLAKE2 がハードウェアアクセラレーションを利用する SHA-256 より常に速いとは考えないでください。並列ハッシュ計算では同じストレージデバイスへのアクセスが競合する場合があるため、--jobs を増やす前に、自分のデータセットでワーカー数ごとの性能を測定してください。
ダウンロードした単一ファイルを移動後に検証する方法は、別記事の b2sum による検証手順を参照してください。
