15.2. `hmac` --- メッセージ認証のための鍵付きハッシュ化¶

ソースコード: Lib/hmac.py

このモジュールでは RFC 2104 で記述されている HMAC アルゴリズムを実装しています。

hmac.new(key, msg=None, digestmod=None)¶: 新しい hmac オブジェクトを返します。 key は秘密鍵を与える bytes または bytearray オブジェクトです。msg が与えられると、update(msg) が呼び出されます。digestmod は利用するダイジェスト名、ダイジェストコンストラクターまたは HMAC オブジェクトのモジュールです。hashlib.new() に与えることができる任意の名前をサポートし、デフォルトは hashlib.md5 のコンストラクターです。

バージョン 3.4 で変更: 引数 key に bytes または bytearray オブジェクトを渡せるようになりました。引数 msg に hashlib がサポートする全てのタイプを渡せるようになりました。引数 digestmod にハッシュアルゴリズム名を渡せるようになりました。

バージョン 3.4 で非推奨: MD5 が digestmod の暗黙のデフォルトダイジェストとなるのは廃止予定です。

HMAC オブジェクトは以下のメソッドを持っています:

HMAC.update(msg)¶: hmac オブジェクトを msg で更新します。このメソッドの呼出の繰り返しは、それらの引数を全て結合した引数で単一の呼び出しをした際と同じになります。すなわち m.update(a); m.update(b) は m.update(a + b) と等価です。

バージョン 3.4 で変更: 引数 msg は hashlib がサポートしているあらゆる型のいずれかです。

HMAC.digest()¶: これまで update() メソッドに渡されたバイト列のダイジェスト値を返します。これはコンストラクタに与えられた digest_size と同じ長さのバイト列で、 NUL バイトを含む非 ASCII 文字が含まれることがあります。

警告

digest() の出力結果と外部から供給されたダイジェストを検証ルーチン内で比較しようとするのであれば、タイミング攻撃への脆弱性を減らすために、 == 演算子ではなく compare_digest() を使うことをお奨めします。

HMAC.hexdigest()¶: digest() と似ていますが、返される文字列は倍の長さとなり、16進形式となります。これは、電子メールなどの非バイナリ環境で値を交換する場合に便利です。

警告

hexdigest() の出力結果と外部から供給されたダイジェストを検証ルーチン内で比較しようとするのであれば、タイミング攻撃への脆弱性を減らすために、 == 演算子ではなく compare_digest() を使うことをお奨めします。

HMAC.copy()¶: hmac オブジェクトのコピー ("クローン") を返します。このコピーは最初の部分文字列が共通になっている文字列のダイジェスト値を効率よく計算するために使うことができます。

ハッシュオブジェクトには次のような属性があります:

このモジュールは以下のヘルパ関数も提供しています:

hmac.compare_digest(a, b)¶: a == b を返します。この関数は、内容ベースの短絡的な振る舞いを避けることによってタイミング分析を防ぐよう設計されたアプローチを用い、暗号化に用いるのに相応しいものとしています。 a と b は両方が同じ型でなければなりません: (例えば HMAC.hexdigest() が返したような ASCII のみの) str または bytes-like object のどちらか一方。

注釈

a と b が異なる長さであったりエラーが発生した場合には、タイミング攻撃で理論上 a と b の型と長さについての情報が暴露されますが、その値は明らかになりません。

バージョン 3.3 で追加.

参考

15.2. hmac --- メッセージ認証のための鍵付きハッシュ化¶