Ruby と SHA384 による安全なファイル検証
Ruby でダウンロードしたファイルを検証するには、OpenSSL の SHA384 ダイジェストでバイト列をハッシュ化し、信頼できるチェックサムと比較します。以下のスクリプトは、ファイルとチェックサムのペアを一つ以上受け取り、いずれかの検証に失敗するとゼロ以外の終了ステータスを返すため、自動ジョブで使えます。
信頼できるチェックサムの入手
SHA-384 は SHA-2 ファミリーに属し、384 ビットのダイジェストを生成します。これは 48 バイト、または 96 桁の十六進数です。配布元や既存のワークフローが SHA384 チェックサムを提供している場合に使います。SHA256 で作成された参照値は、SHA384 では検証できません。
期待するチェックサムは、配布元の認証済み HTTPS リリースページや、署名を検証済みの署名付きチェックサムマニフェストなど、信頼できるソースから入手します。ファイルと参照用チェックサムの両方を差し替えられると、検証を通過させられてしまいます。ハッシュ化で検出できるのは参照値に対する変更です。ファイルの改ざんを防いだり、実行しても安全だと証明したりするものではありません。Ruby の OpenSSL ドキュメントでは、ダイジェストがデジタル署名の一部としても使われる仕組みを説明しています。
Ruby と OpenSSL の確認
OpenSSL 拡張機能を備えた Ruby が必要です。ここで紹介するコマンドは、Linux 上の
Ruby 3.4.10、Ruby/OpenSSL 3.3.3、OpenSSL 3.6.4 でテストしています。シェルの例では Bash を使います。GNU Coreutils の sha384sum は、後述する独立した比較を行う場合にのみ必要です。Ruby がない場合は、公式の Ruby インストールガイドで、使用するプラットフォームの手順に従ってください。
先に進む前に、インタープリター、リンクされているライブラリ、SHA384 の利用可否を確認します。
ruby -ropenssl -e 'puts RUBY_DESCRIPTION; puts "Ruby/OpenSSL #{OpenSSL::VERSION}"; puts OpenSSL::OPENSSL_LIBRARY_VERSION; puts "SHA384: #{OpenSSL::Digest.new("SHA384").digest_length} bytes"'
最終行が SHA384: 48 bytes になることを確認してください。OpenSSL の読み込みやダイジェストの作成に失敗する場合は、検証スクリプトを実行する前に Ruby のインストールを修復してください。PATH 上の openssl コマンドは、Ruby とは異なるライブラリを使う場合があるため、そのバージョンだけでは前提条件を満たしていると判断できません。
検証スクリプトの保存
以下のスクリプト全体を verify_sha384.rb として保存します。各ファイルを 8 KiB のチャンクに分けて読み取り、バッファーを再利用するため、ファイル全体をメモリに読み込むことはありません。Ruby の
IO#readは、正の長さを指定すると、空のファイルを含め、ファイル終端で
nil を返します。各チャンクは
OpenSSL::Digest#updateに渡されます。
require 'openssl'
def sha384_hash(path)
digest = OpenSSL::Digest.new('SHA384')
File.open(path, 'rb') do |file|
buffer = ''.b
digest.update(buffer) while file.read(8192, buffer)
end
digest.hexdigest
end
if ARGV.empty? || ARGV.length.odd?
warn 'Usage: ruby verify_sha384.rb FILE SHA384 [FILE SHA384 ...]'
exit 2
end
failed = false
ARGV.each_slice(2) do |path, expected|
unless /\A[0-9a-fA-F]{96}\z/.match?(expected)
warn "#{path}: ERROR (expected 96 hexadecimal characters)"
failed = true
next
end
begin
actual = sha384_hash(path)
if actual == expected.downcase
puts "#{path}: OK"
else
warn "#{path}: FAILED (SHA384 mismatch)"
failed = true
end
rescue SystemCallError, IOError => error
warn "#{path}: ERROR (#{error.message})"
failed = true
end
end
exit(failed ? 1 : 0)
ダイジェストだけを渡し、ファイル名、sha384- 接頭辞、前後の空白は含めないでください。十六進数の英字は大文字でも受け付けます。スクリプトは公開チェックサムを == で比較します。このワークフローには、タイミング情報の漏えいから保護すべき秘密のチェックサムはありません。HMAC などの秘密の認証子については、比較ループを手書きしなくても済むように、Ruby が定時間比較メソッドを提供しています。
結果が既知のファイルの検証
verify_sha384.rb を置いた作業用ディレクトリで、次のコマンドを Bash で実行します。これにより、example.txt が作成されます。内容は
abc という三つのバイトだけで、末尾の改行は含みません。作成時には既存ファイルの上書きを拒否します。作成に失敗すると、&& の連鎖は検証前に停止します。セットアップを繰り返す場合は、別の作業用ディレクトリを使ってください。
ruby -e 'File.open("example.txt", "wbx") { |file| file.write("abc") }' &&
EXPECTED_SHA384='cb00753f45a35e8bb5a03d699ac65007272c32ab0eded1631a8b605a43ff5bed8086072ba1e7cc2358baeca134c825a7' &&
ruby verify_sha384.rb example.txt "$EXPECTED_SHA384"
結果は次のとおりです。
example.txt: OK
終了ステータスは 0 です。実際のダウンロードを検証する場合は、そのファイルのパスと、該当するリリースの信頼できる SHA384 チェックサムに置き換えてください。空白を含むパスは引用符で囲みます。検証スクリプトはファイルを読み取り専用で開き、検証成果物は作成しません。
GNU Coreutils がある場合は、sha384sum を使って、サンプルのチェックサムを独立して計算します。
sha384sum --binary -- example.txt
最初のフィールドが EXPECTED_SHA384 と等しいことを確認してください。ダウンロード直後のファイルからハッシュを計算すると比較に役立ちますが、それだけでは、そのダウンロードの信頼できる参照値にはなりません。
バッチの検証失敗をジョブの失敗に反映
EXPECTED_SHA384 の設定が維持されるよう、同じ Bash セッションを使います。空のファイルを作成し、ファイルとチェックサムのペアをもう一つ渡して、両方のサンプルを検証します。
ruby -e 'File.open("empty.bin", "wbx") {}' &&
EMPTY_SHA384='38b060a751ac96384cd9327eb1b1e36a21fdb71114be07434c0cc7bf63f6e1da274edebfe76f65fbd51ad2f14898b95b' &&
ruby verify_sha384.rb example.txt "$EXPECTED_SHA384" empty.bin "$EMPTY_SHA384"
両方のファイルで OK が表示されるはずです。コマンドは 0 で終了します。empty.bin の作成時も、既存の出力先がある場合は拒否します。次に、破棄してよい最初のサンプルに改行を追加し、バッチを再実行します。
ruby -e 'File.open("example.txt", "ab") { |file| file.write("\n") }' &&
ruby verify_sha384.rb example.txt "$EXPECTED_SHA384" empty.bin "$EMPTY_SHA384"
example.txt は標準エラー出力に
FAILED (SHA384 mismatch) を表示し、empty.bin は引き続き標準出力に OK を表示します。バッチは 1 で終了します。後で成功しても、それ以前の失敗は取り消されません。スクリプトは渡されたすべてのペアを検証し、どちらの参照チェックサムも書き換えません。
終了コードは、すべてのファイルが一致した場合は 0、いずれかのファイルが不一致、期待するチェックサムの形式が不正、または読み取り不能の場合は 1、ペアのリストが未指定または不完全な場合は 2 です。ジョブでは、検証スクリプトをその処理手順の最後のコマンドにするか、後続のコマンドを実行する前に、ゼロ以外のステータスを明示的に伝播させてください。エラーメッセージを表示するだけでは、シェルジョブは失敗しません。
検証失敗の原因調査
- expected 96 hexadecimal characters: SHA384 ダイジェストだけをコピーしてください。SHA256 チェックサム、Base64 値、
sha384sumの出力行全体は、有効な引数ではありません。 - SHA384 mismatch: リリース、ファイル名、ダウンロードの完了状況、想定するアルゴリズムを確認してください。検証を通すためだけに、参照値を新しいハッシュに置き換えないでください。
- ファイルまたは権限のエラー: 作業ディレクトリ、パス、ジョブを実行するアカウントの読み取り権限を確認してください。他のファイルが検証を通過しても、読み取りに失敗すると
1を返します。
検証対象のバイト列の保持
バイナリモードは、ダイジェストに渡すバイト列を保持します。Ruby のファイルモードのドキュメントでは、'b' が Windows の改行変換を無効にする仕組みを説明しています。これは、LF のファイルと CRLF のファイルを同一にするものではありません。両者は異なるバイト列を含むため、チェックサムも異なるはずです。検証前に改行を正規化したり、空白を削除したり、テキストを再エンコードしたりしないでください。そのような処理を行うと、ダウンロードしたファイルではなく、変換後の内容を検証することになります。
書き込みが完了した通常ファイルを使い、検証中もその後の使用中も変更されないようにしてください。この小さな CLI は、ファイルをロックしたり、検証成功後に別のプロセスがファイルを差し替えるのを防いだりするものではありません。検証済みのファイルだけでなく、信頼できる参照値も保護してください。
Transloadit のワークフロー内でハッシュ化する場合は、/file/hash のドキュメントを参照してください。ファイル処理中にチェックサムを生成する場合も、信頼できる参照値が必要な点は同じです。
