HMAC生成

仕組み

HMACは、メッセージが改ざんされていないことと、作成者が共有の秘密を持っていることを同時に証明します。ウェブ上の多くの場所で、Webhook、APIリクエスト、ダウンロードリンクの署名に使われています。

単なるハッシュとは、大事な点で違います

メッセージのSHA-256は誰でも計算できるため、ハッシュだけでは誰が作成したかを何も証明できません。メッセージを変えてハッシュを再計算すれば、誰にも見分けがつきません。HMACは計算に秘密鍵を組み込むので、鍵がなければ再計算できません。これが要点であり、Webhookの署名にハッシュではなくHMACが使われる理由です。

安全に検証する

サーバーでHMACを確認するときは、一定時間で比較する関数を使ってください。Nodeならcrypto.timingSafeEqual、PHPならhash_equalsです。通常の==は2バイトが異なった時点で結果を返すので、その所要時間から署名のどこまでが正しかったかが漏れ、根気があれば署名を偽造できます。これは理論上の話ではなく、実際に行われる攻撃です。

どのアルゴリズムか

指定がなければSHA-256を使ってください。SHA-1を含めているのは、HMAC-SHA-1を今も求める古いAPIが多いためです。HMAC-SHA-1は単独のSHA-1のようには破られていませんが、新しく選ぶ理由はありません。

16進数かBase64か

相手側が何を期待しているかだけで決まります。16進数は長さが2倍ですが読みやすく、Base64はコンパクトでHTTPヘッダーによく使われます。同じ署名を両方の形式で表示します。

鍵はここから出ません

ブラウザ標準のWeb Crypto APIで生成します。鍵もメッセージもどこにも送信されません。これがこの種のツールを提供する唯一の責任ある方法です。秘密をアップロードする署名ツールは、秘密が守っているものそのものを手放してしまいます。