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

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

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

hmac.new(key, msg=None, digestmod='')

Return a new hmac object. key is a bytes or bytearray object giving the secret key. If msg is present, the method call update(msg) is made. digestmod is the digest name, digest constructor or module for the HMAC object to use. It may be any name suitable to hashlib.new(). Despite its argument position, it is required.

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

Deprecated since version 3.4, removed in version 3.8: MD5 as implicit default digest for digestmod is deprecated. The digestmod parameter is now required. Pass it as a keyword argument to avoid awkwardness when you do not have an initial msg.

hmac.digest(key, msg, digest)

与えられたsecret key と digest の msg のダイジェストを返します。この関数は HMAC(key, msg, digest).digest() に似ていますが、最適化されたCやインラインの実装を使用しており、メモリに収まるメッセージに対しては高速です。パラメータ key 、 msg 、および digest は、 new() と同じ意味を持ちます。

CPython実装の詳細、最適化されたC実装は、OpenSSLがサポートするダイジェストアルゴリズムの文字列と名前が digest の場合にのみ使用されます。

バージョン 3.7 で追加.

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.digest_size

生成された HMAC ダイジェストのバイト数。

HMAC.block_size

内部で使われるハッシュアルゴリズムのブロックのバイト数。

バージョン 3.4 で追加.

HMAC.name

このHMAC の正規名で、例えば hmac-md5 のように常に小文字です。

バージョン 3.4 で追加.

バージョン 3.9 で非推奨: The undocumented attributes HMAC.digest_cons, HMAC.inner, and HMAC.outer are internal implementation details and will be removed in Python 3.10.

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

hmac.compare_digest(a, b)

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

注釈

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

バージョン 3.3 で追加.

バージョン 3.9 で変更: The function uses OpenSSL's CRYPTO_memcmp() internally when available.

参考

hashlib モジュール

セキュアハッシュ関数を提供する Python モジュールです。