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

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

このモジュールは RFC 2104 で記述された HMAC アルゴリズムを実装しています。 このインターフェースでは、ダイジェストのサイズが 固定 された任意のハッシュ関数を使えます。 特に、SHAKE-128 や SHAKE-256 などの出力長を拡張できる関数は HMAC では使えません。

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

新しい hmac オブジェクトを返します。 key は秘密鍵を指定する bytes または bytearray オブジェクトです。 msg が指定されていれば、メソッド update(msg) を呼び出します。 digestmod は HMAC オブジェクトで使うダイジェストの名前、コンストラクタ、またはモジュールです。 名前には hashlib.new() に指定できるものを使えます。 引数の位置にかかわらず、指定は必須です。

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

バージョン 3.8 で変更: digestmod 引数の指定が必須になりました。 初期値の msg がない場合は、呼び出しが煩雑になるのを避けるためにキーワード引数として渡してください。

hmac.digest(key, msg, digest)

指定された秘密鍵 key と digest を使って msg のダイジェストを返します。 この関数は HMAC(key, msg, digest).digest() と同等ですが、最適化された C の実装またはインライン実装を使うため、メモリに収まるメッセージではより高速です。 引数 key、msg、digest の意味は new() と同じです。

CPython の実装上の詳細として、最適化された C 実装が使われるのは、digest が OpenSSL でサポートされているダイジェストアルゴリズムの名前を表す文字列の場合だけです。

Added in version 3.7.

class hmac.HMAC

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

HMAC.update(msg)

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

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

HMAC.digest()

これまで update() メソッドに渡されたバイト列のダイジェストを返します。 返される bytes オブジェクトの長さは、コンストラクタに指定したダイジェストの digest_size と同じです。 NUL バイトを含め、非 ASCII のバイトが含まれることがあります。

警告

検証処理で digest() の出力を外部から与えられたダイジェストと比較するときは、タイミング攻撃に対する脆弱性を軽減するため、 == 演算子の代わりに compare_digest() 関数を使うことを推奨します。

HMAC.hexdigest()

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

警告

検証処理で hexdigest() の出力を外部から与えられたダイジェストと比較するときは、タイミング攻撃に対する脆弱性を軽減するため、 == 演算子の代わりに compare_digest() 関数を使うことを推奨します。

HMAC.copy()

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

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

HMAC.digest_size

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

HMAC.block_size

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

Added in version 3.4.

HMAC.name

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

Added in version 3.4.

バージョン 3.10 で変更: ドキュメントに記載されていなかった属性 HMAC.digest_cons、HMAC.inner、HMAC.outer を削除しました。

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

hmac.compare_digest(a, b)

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

注釈

a と b の長さが異なる場合やエラーが発生した場合、理論上はタイミング攻撃によって a と b の型や長さに関する情報が漏れる可能性がありますが、値は漏れません。

Added in version 3.3.

バージョン 3.10 で変更: OpenSSL の CRYPTO_memcmp() が利用可能な場合、この関数は内部でそれを使います。

参考

hashlib モジュール

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