"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 モジュールです。
