HMAC 生成ツール

HMAC のしくみ

HMAC（hash-based message authentication code、ハッシュベースのメッセージ認証コード、RFC 2104）は、暗号学的ハッシュ関数と秘密鍵を組み合わせたものです。メッセージに対して正しい値を作れるのは鍵を知っている人だけなので、HMAC が一致すれば、メッセージが改ざんされていないことと、鍵の所有者から送られたものであることの 2 点が同時に証明されます。

計算式は H((K ⊕ opad) ‖ H((K ⊕ ipad) ‖ message)) です。鍵はハッシュ関数のブロックサイズ（MD5、SHA-1、SHA-256 では 64 バイト、SHA-384 と SHA-512 では 128 バイト）より長い場合は先にハッシュ化され、そのサイズになるまでゼロで埋められます。次に、ipad（0x36 のバイト列）と XOR を取ったものでメッセージに対する内側のハッシュを計算し、opad（0x5c のバイト列）と XOR を取ったもので内側の結果に対する外側のハッシュを計算します。単純な SHA-256(key ‖ message) には外側のハッシュがないため、タグを 1 つ見た人なら誰でも、鍵を知らなくてもメッセージにデータを追加して有効な新しいタグを計算できてしまいます（伸長攻撃）。

出力の長さは元のハッシュ関数と同じで、HMAC-SHA256 なら 32 バイト（16進数で 64 文字）です。RFC 2104 では少なくともこの長さの鍵を使うよう推奨されており、ランダム Base64 生成ツールで適切な鍵を作成できます。

HMAC 署名が使われる場面

• GitHub の Webhook。X-Hub-Signature-256 ヘッダーは、sha256= の後に、リクエストの生のボディに対して Webhook のシークレットを鍵として計算した HMAC-SHA256 を16進数で続けたものです。ヘッダーの値全体を「比較対象」に貼り付けてもかまいません。sha256= プレフィックスは無視されます。
• Stripe の Webhook。Stripe-Signature ヘッダーには、タイムスタンプ t と署名 v1 が含まれます。署名は、タイムスタンプ、ドット、生のボディをつなげたものに対し、エンドポイントのシークレット（whsec_...）をテキストのまま鍵として計算した HMAC-SHA256 の16進数です。
• Shopify の Webhook。X-Shopify-Hmac-Sha256 には、生のボディに対してアプリのクライアントシークレットを鍵として計算した HMAC-SHA256 が Base64 で入っています。「出力形式」で「Base64」を選ぶか、ヘッダーの値を「比較対象」に貼り付けてください。
• AWS 署名バージョン 4。署名鍵は HMAC-SHA256 を連鎖させて導出します。まず AWS4 とシークレットアクセスキーをつなげたものを鍵として日付の HMAC を計算し、続いてリージョン、サービス、aws4_request を、それぞれ直前の結果を鍵として順に処理します。あるステップの出力を次のステップの鍵として使うには、「鍵の形式」を「16進数」に設定してください。
• JSON Web Token。HS256、HS384、HS512 は、エンコード済みのヘッダー、ドット、エンコード済みのペイロードをつなげたものに対する HMAC-SHA256、-384、-512 です。トークンの 3 番目の部分はその HMAC を URL セーフの Base64 で表したもので、「比較対象」にそのまま貼り付けられます。トークン全体の検証には JWT デコーダーをご利用ください。

HMAC は必ず、受信したとおりの生のボディに対して計算してください。JSON を解析してから再びシリアライズすると、空白やキーの順序が変わります。改行が 1 つ増えただけでも、まったく異なる HMAC になります。

コードで HMAC を計算する

# Python
import hmac, hashlib
sig = hmac.new(b'key', b'message', hashlib.sha256).hexdigest()
hmac.compare_digest(sig, received)        # 定数時間で比較

// Node.js
const crypto = require('crypto');
const sig = crypto.createHmac('sha256', 'key').update('message').digest('hex');
// timingSafeEqual は長さが異なると例外を投げるため、先に長さを確認します
crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(received));

// PHP：メッセージを鍵より先に渡します
$sig = hash_hmac('sha256', 'message', 'key');
hash_equals($sig, $received);

# OpenSSL：テキストの鍵と、同じ鍵を16進数で指定する例
printf '%s' 'message' | openssl dgst -sha256 -hmac 'key'
printf '%s' 'message' | openssl dgst -sha256 -mac HMAC -macopt hexkey:6b6579

# テストベクター：鍵 "key"、メッセージ "The quick brown fox jumps over the lazy dog"
# HMAC-SHA256 = f7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbc2d1a3cd8

独自のコードで署名を検証する場合は、上の例のような定数時間の比較を使用してください。単純な == は最初に異なる文字が見つかった時点で比較を終えるため、その時間差を手がかりに、攻撃者が有効な署名を 1 バイトずつ突き止められるおそれがあります。Stripe のようにタイムスタンプを含む方式では、タイムスタンプが数分以上前のリクエストも拒否してください。これでリプレイ攻撃を防げます。