HMAC-SHA256署名の検証方法、値を突き合わせて確認

ウェブフックやAPIレスポンスに含まれていたHMAC署名値が、自分で計算した値と一致しない場合、その多くはセキュリティ侵害ではなく、メッセージ・秘密鍵・ハッシュアルゴリズムという3つの入力のどれかがわずかに異なっていることが原因です。この3つが完全に同じでなければ、同じ署名値にはなりません。
この記事では、実際に計算した値を例に示しながら、署名が合わないときに何から確認すべきかを整理します。専門家の判断が必要な問題ではなく、同じ入力を入れ直して同じ値になるかを目で見て比べれば済む手順です。
まとめ ① HMAC署名値はメッセージ・秘密鍵・ハッシュアルゴリズムの3つの入力から計算され、この3つが完全に同じでなければ同じ値にはなりません。 ② 値が合わない原因は、ほとんどが空白・改行、大文字小文字、エンコーディング(16進数/Base64)、アルゴリズムの選択違いです。 ③ 検証は、同じメッセージ・鍵・アルゴリズムで自分でもう一度計算し、出てきた値を文字単位で比較することで行います。
ウェブフックの署名が合わないときによく起きること
外部サービスが決済完了や注文ステータスの変更といったイベントを通知するウェブフックを送るとき、リクエスト本文(payload)と一緒に、その本文から計算したHMAC署名値をヘッダーに載せて送る方式がよく使われます。受信側は同じ秘密鍵で自分も署名を計算し、ヘッダーで受け取った値と一致するかどうかを比較します。
この比較が失敗すると、コードに誤りがあるか、リクエストが改ざんされたのではないかと疑いがちです。ところが実際には、元のpayloadをそのまま使わず、一度パースしてから再び文字列に戻す過程で、空白が1つ増えたり改行が付いたりしているケースがよくあります。
HMACは、こうしたわずかな違いに意図的に敏感に反応するように設計されています。メッセージの1文字、秘密鍵の大文字小文字1つ、選んだハッシュアルゴリズム1つが違うだけで、結果の値は最初から最後までまったく別の文字列になります。
ツールを使わずにHMAC値を自分で計算してみる方法
HMACはRFC 2104で定義された標準的な計算方式で、秘密鍵とハッシュアルゴリズムを使ってメッセージに署名を付けます。この計算は、特定のプログラムがなくてもターミナルでそのまま再現できます。
macOSとLinuxにはOpenSSLが最初から入っているので、次のコマンドで同じ計算ができます。
echo -n "order:1001,amount:5000" | openssl dgst -sha256 -hmac "mySecretKey"
このコマンドを実行すると、次の結果が得られます。
SHA2-256(stdin)= 148bec9dd63667edc6b3d37f9e7f5607c75144bd267159d843ec898b0667cea4
メッセージは order:1001,amount:5000、秘密鍵は mySecretKey、アルゴリズムはSHA-256を使ったときに得られる値です。同じ3つの入力を入れれば、OSやプログラミング言語に関係なく、常にこの値になります。
他の言語でも同じ値になるか確認する
実際にPythonのhmacモジュールで同じメッセージと鍵を計算しても、同じ値になることを確認しました。
import hmac, hashlib
hmac.new(b"mySecretKey", b"order:1001,amount:5000", hashlib.sha256).hexdigest()
echoで -n オプションを付け忘れると、メッセージの末尾に改行文字が自動的に付き、同じメッセージ・鍵・アルゴリズムでもまったく別の値になります。この問題は、次の項目で実際の値を使って改めて示します。
無料ツール「HMAC署名ジェネレーター」でも実際に確認してみましょう。
ブラウザ内でWeb Crypto APIによりすぐに計算され、入力したメッセージと秘密鍵はサーバーに送信されません。

署名が合わないときによく見落とす4つのポイント
同じメッセージ order:1001,amount:5000 と同じ秘密鍵 mySecretKey でSHA-256の署名値を計算し、ごく小さな部分を1つずつ変えてみると、次のような結果になります。
元のメッセージ: order:1001,amount:5000
SHA-256の結果: 148bec9dd63667edc6b3d37f9e7f5607c75144bd267159d843ec898b0667cea4
末尾に改行を追加: order:1001,amount:5000 (後ろに改行文字が1つ)
SHA-256の結果: 015bc2c0bf5cc82fd005e37b7a2b0ae8777e41a109bae303b263aaa162f32cff
先頭の文字だけ大文字: Order:1001,amount:5000
SHA-256の結果: 11c1403b448d39601f4a14119514f6a44b16bdcb378f384d767ffafc0054ffb2
メッセージ自体がわずかに違う場合
メッセージは見た目にはほとんど同じなのに、結果の値は先頭の桁からまったく違います。これが「署名が合わない」という問題の実態であることが少なくありません。秘密鍵が漏えいしたわけでもロジックが間違っているわけでもなく、比較している2つの文字列そのものが実際には違う、というケースです。
エンコーディングやアルゴリズムが違う場合
同じ署名でも表現形式が違えば、文字列としては別物に見えます。上の元の例の結果値をBase64で表すと FIvsndY2Z+3Gs9N/nn9WB8dRRL0mcVnYQ+yJiwZnzqQ= になりますが、これは同じ署名を16進数の代わりにBase64で表記しただけです。
ヘッダーで受け取った値は16進数なのに、自分の側はBase64で計算して比較すれば、値が違って見えるのは当然です。
アルゴリズムそのものが違えば、値の長さからして異なります。同じメッセージ・鍵でも、SHA-1は40桁、SHA-256は64桁、SHA-384は96桁、SHA-512は128桁の16進数文字列になります。
上のメッセージをSHA-1で計算すると d67244f34d44c077a2a3dada4528c8284c2951cb となり、SHA-256とは長さも値も異なります。4つの原因を整理すると次のようになります。
| 原因 | 症状 | 確認方法 |
|---|---|---|
| メッセージ末尾の空白・改行 | 原文は同じに見えるのに値が違う | メッセージ末尾にスペース・改行がないか直接確認 |
| 大文字小文字の違い | フィールド名・値の一部だけが違う | 元のpayloadをそのままコピーしたか文字単位で照合 |
| エンコーディングの違い(16進数/Base64) | 値の長さ・構成する文字が違う(Base64は +, /, = を含む) | 比較対象の署名が16進数かBase64かを先に確認 |
| アルゴリズムの不一致 | 値の長さそのものが違う(40/64/96/128桁) | 送信側が明示したアルゴリズムと、選択したアルゴリズムが同じか確認 |
まとめ
- HMAC署名値はメッセージ・秘密鍵・アルゴリズムの3つの入力で決まり、3つがすべて同じでなければ同じ値にはなりません。
- メッセージに空白や改行が1つ増えるだけでも、結果の値はまったく変わります。
- 値の長さが違う場合は、十中八九エンコーディング(16進数/Base64)かアルゴリズムが違います。
- 検証は、同じ3つの入力を入れて再計算した値と、受け取った値を文字単位で比較すれば十分です。
- openssl dgstコマンドやブラウザツールで自分で再計算してみると、どの入力が違うのかを絞り込めます。
ブラウザ内でWeb Crypto APIによりすぐに計算され、入力したメッセージと秘密鍵はサーバーに送信されません。
よくある質問
同じメッセージと鍵なのに、値が毎回違って出ます。これは正常ですか?
いいえ。HMACはメッセージ・秘密鍵・アルゴリズムが同じなら、いつどこで計算しても常に同じ値になる決定論的(deterministic)な計算です。値が変わり続けるなら、3つのうちのどれかが実際に変わっているということです。メッセージに現在時刻のように毎回変わる値が混ざっているケースがよくあります。
16進数とBase64では、どちらの形式が正しいのですか?
どちらも同じ結果バイトを表現する方法の違いにすぎず、どちらか一方が正解というわけではありません。署名を送った側がどの形式でエンコードしているかに合わせれば値が一致します。値が0-9、a-fだけで構成されていれば16進数、+、/、=の文字が混ざっていればBase64です。
アルゴリズムがわからないときは、どうやって特定すればいいですか?
メッセージと鍵はそのままにして、SHA-256、SHA-384、SHA-512、SHA-1の順にそれぞれ計算し、受け取った値と長さが同じアルゴリズムから照合していきます。ドキュメントやAPI仕様にアルゴリズムが明記されていることも多いので、まずそこを確認するのが確実です。
メッセージに日本語や特殊文字が入っていると、値は変わりますか?
エンコーディング方式が同じなら(例: UTF-8)、同じ文字列は常に同じバイト列に変換されるので同じ値になります。ただし保存・伝送の過程で文字エンコーディングが変わると(例: 片方はUTF-8、もう片方はEUC-KR)、同じ文字に見えても実際のバイト列が変わり、結果の値が変わることがあります。
この記事は韓国語の原文をもとに作成しています。 韓国語の原文を読む