secrets.compare_digestとは?==との違いを実測|TypeErrorの直し方・hmac.compare_digestとの関係(Python)

secrets.compare_digest(a, b)は、2つの文字列またはバイト列が等しいかをTrue/Falseで返す関数で、==と違って「どこで食い違ったか」によって比較時間が変わりにくい作りになっています。APIキー、トークン、署名、パスワードのハッシュなど、秘密の値を照合するときに==の代わりに使います。

この記事では、使い方、==との違いを実測した結果、よく出るTypeError、hmac.compare_digestとの関係、Webhook署名とパスワード照合の実例を、Python 3.12で実行した結果つきで説明します(2026年10月18日確認)。

secrets.compare_digestの使い方

import secrets, hmac

print(secrets.compare_digest("abc", "abc"))
print(secrets.compare_digest("abc", "abd"))
print(secrets.compare_digest(b"abc", b"abcd"))
print(secrets.compare_digest is hmac.compare_digest)

実行結果:

True
False
False
True
項目 内容
書き方 secrets.compare_digest(a, b)
戻り値 等しければTrue、違えばFalse
渡せる型 ASCIIだけのstr同士、またはbytesなどのバイト列同士
追加されたバージョン secretsモジュールは3.6、hmac.compare_digestは3.3
中身 hmac.compare_digestと同じ関数(上の4行目でisがTrue)

公式ドキュメントでは、secrets.compare_digestは「タイミング攻撃のリスクを減らす定数時間比較で、aとbが等しければTrueを返す」と説明され、詳細はhmac.compare_digest()を見るよう案内されています(secrets、hmac、2026年10月18日確認)。どちらから読み込んでも同じです。

==との違いを実測する

==は、違う文字が見つかった時点で比較をやめます。そのため「先頭で違う」ときは速く、「最後で違う」ときは遅くなります。1万文字の文字列で、違う位置を変えて計ってみました。

import secrets, timeit

secret = "a" * 10000
early = "b" + "a" * 9999   # 先頭で違う
late  = "a" * 9999 + "b"   # 最後で違う

def t(f):
    return min(timeit.repeat(f, number=20000, repeat=5)) / 20000 * 1e9

print(f"==             先頭が違う: {t(lambda: secret == early):8.0f} ns")
print(f"==             最後が違う: {t(lambda: secret == late):8.0f} ns")
print(f"compare_digest 先頭が違う: {t(lambda: secrets.compare_digest(secret, early)):8.0f} ns")
print(f"compare_digest 最後が違う: {t(lambda: secrets.compare_digest(secret, late)):8.0f} ns")

実行結果(Apple Silicon搭載のMac・Python 3.12での1回の測定):

==             先頭が違う:       23 ns
==             最後が違う:      277 ns
compare_digest 先頭が違う:     4177 ns
compare_digest 最後が違う:     4149 ns

==は違う位置によって10倍以上の差が出ましたが、compare_digestはどちらでもほぼ同じ時間でした。そのかわりcompare_digestは全体を最後まで見るので、==より遅くなります。秘密の値の照合以外で使う必要はありません。

なぜ==では危ないのか(タイミング攻撃)

比較にかかる時間が「何文字目まで合っていたか」で変わると、外から何度も試して応答時間を測ることで、正しい値を1文字ずつ推測される可能性があります。これをタイミング攻撃と呼びます。全体を総当たりするより、はるかに少ない試行で済んでしまうのが問題です。

ネットワーク越しでは揺らぎが大きく、実際に突破するには大量の試行が必要ですが、照合する側がcompare_digestに変えるだけで防げるので、秘密の値には最初から使っておくのが定石です。

比較する値 compare_digestを使うか
APIキー・アクセストークン・セッションID 使う
Webhookなどの署名(HMAC) 使う
パスワードのハッシュ値 使う
CSRFトークン・パスワード再設定のトークン 使う
ユーザー名・設定値・ファイル名 不要(==でよい)

判断の基準は「攻撃者が何度でも試せる、秘密の値かどうか」です。

よくあるエラー:TypeError

compare_digestは==より受け付ける型が厳しく、次の3つでエラーになります。

import secrets
for a, b in [("あいう", "あいう"), ("abc", b"abc"), (None, "abc")]:
    try:
        secrets.compare_digest(a, b)
    except TypeError as e:
        print(type(e).__name__ + ":", e)

実行結果:

TypeError: comparing strings with non-ASCII characters is not supported
TypeError: a bytes-like object is required, not 'str'
TypeError: unsupported operand types(s) or combination of types: 'NoneType' and 'str'
エラーメッセージ 原因 直し方
comparing strings with non-ASCII characters is not supported 日本語など非ASCIIの文字列を渡した 両方を.encode("utf-8")でバイト列にする
a bytes-like object is required, not ‘str’ strとbytesを混ぜた どちらかに揃える
unsupported operand types(s) … Noneなどが入っていた(ヘッダが無いなど) 先にNoneを判定してFalseを返す

日本語を含む値はバイト列にすれば比較できます。

import secrets
a = "パスワード".encode("utf-8")
b = "パスワード".encode("utf-8")
print(secrets.compare_digest(a, b))

実行結果:

True

実例1:Webhookの署名を検証する

外部サービスから届いたWebhookが本物かを、共有の秘密鍵で作ったHMAC署名で確かめる処理です。署名の照合にcompare_digestを使います。

import hmac, hashlib, secrets

SECRET = b"whsec_example"

def sign(payload: bytes) -> str:
    return hmac.new(SECRET, payload, hashlib.sha256).hexdigest()

def verify(payload: bytes, signature: str) -> bool:
    expected = sign(payload)
    return secrets.compare_digest(expected, signature)

body = b'{"event": "paid", "amount": 1200}'
sig = sign(body)
print(sig[:16] + "...")
print(verify(body, sig))
print(verify(b'{"event": "paid", "amount": 9999}', sig))

実行結果:

f3bec9dbae05b9b0...
True
False

本文を書き換えると署名が合わなくなり、Falseになります。実際のサービスでは、署名がどのヘッダに、どの形式(16進かBase64か、sha256=の接頭辞があるか)で入るかは各サービスのドキュメントで確認してください。

実例2:パスワードのハッシュを照合する

パスワードは平文で保存せず、ソルト付きの一方向ハッシュにして保存します(secretsの公式ドキュメントの注記より)。標準ライブラリだけで書くならhashlib.scryptが使えます。

import hashlib, secrets

def hash_password(password: str, salt: bytes) -> bytes:
    return hashlib.scrypt(password.encode("utf-8"), salt=salt, n=16384, r=8, p=1)

salt = secrets.token_bytes(16)
stored = hash_password("correct horse", salt)

def check(password: str) -> bool:
    return secrets.compare_digest(hash_password(password, salt), stored)

print(len(stored))
print(check("correct horse"))
print(check("wrong horse"))

実行結果:

64
True
False

ハッシュ値は入力の長さに関係なく同じ長さ(ここでは64バイト)になるので、長さの違いから情報が漏れる心配もありません。実際のWebアプリでは、フレームワークのパスワード機能や専用ライブラリ(bcrypt、Argon2など)を使うのが一般的です。

compare_digestでも隠せないもの

公式ドキュメントには「aとbの長さが違う場合やエラーが起きた場合、型と長さの情報は理論上タイミング攻撃で漏れうるが、値は漏れない」と注記されています。トークンやハッシュのように長さが固定の値を比べるなら問題になりません。

もう1つは、比較の外で処理時間が変わるケースです。たとえば「ユーザーが存在しなければすぐFalseを返し、存在すればトークンを比較する」と書くと、応答の速さからユーザー名の有無が分かってしまいます。存在しない場合もダミーの値と比較して、処理の流れを揃えるのが対策です。

DUMMY = "0" * 64

user = find_user(name)
stored = user.token if user else DUMMY
ok = secrets.compare_digest(stored, given)
return ok and user is not None

どこまで対策するかは守る対象によりますが、まず==をcompare_digestに置き換えるだけでも効果があります。

よくある質問

Q. secrets.compare_digestとhmac.compare_digestの違いは?

違いはありません。secrets.compare_digestはhmac.compare_digestと同じ関数で、Python 3.12で is による比較がTrueになることを確認しました。

Q. 日本語の文字列でTypeErrorになります

文字列で渡せるのはASCIIだけです。両方を.encode(“utf-8”)でバイト列にしてから比較してください。

Q. いつも==の代わりに使うべきですか?

いいえ。==より遅く、型の制限もあります。APIキー、トークン、署名、パスワードのハッシュなど、攻撃者が何度も試せる秘密の値を照合するときだけ使います。

Q. 長さが違う値を渡すとどうなりますか?

Falseが返ります。ただし公式ドキュメントでは、長さが違う場合は長さの情報が理論上漏れうると注記されています。ハッシュ値など長さが揃った値を比べれば気にする必要はありません。

まとめ

  • secrets.compare_digest(a, b)は等しいかを返す。違う位置で比較時間が変わりにくい
  • ==は違う位置で時間が10倍以上変わった(実測)。秘密の値の照合には使わない
  • 文字列はASCIIのみ。日本語はバイト列に、strとbytesは混ぜない
  • hmac.compare_digestと同じ関数
  • Webhook署名・トークン・パスワードのハッシュの照合で使う

あわせて読みたい

対面・無料|東京・永田町で毎週土曜日13時

この記事のようなコードを、講師に聞きながら動かしてみる

ゼロからはじめるPython入門講座

8年間・累計600回開催/これまで全国で2万人以上が参加

「やはり対面で聞けるのはとても気づきがあり、価値があると思います」

参加者の声

  • 本当に初心者からの講座です。プログラミングに触ったことがなくて大丈夫です
  • 対面だから、その場で聞けます。つまずいた所を持ち帰らずに解決できます
  • 講座は1時間。そのあとも残って学習を続けられ、講師にも質問できます
  • 独学で挫折した方も。糸口が見つかって、講座のあと会員になる方が多くいます

無料で参加する|開催日程を見る

参加費は無料です