"hmac" --- Keyed-Hashing for Message Authentication
***************************************************

**ソースコード:** 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* にハッシ
   ュアルゴリズム名を渡せるようになりました。

   バージョン 3.8 で変更: The *digestmod* argument 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 文字が含まれることがあります
   。

   警告:

     When comparing the output of "digest()" to an externally supplied
     digest during a verification routine, it is recommended to use
     the "compare_digest()" function instead of the "==" operator to
     reduce the vulnerability to timing attacks.

HMAC.hexdigest()

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

   警告:

     When comparing the output of "hexdigest()" to an externally
     supplied digest during a verification routine, it is recommended
     to use the "compare_digest()" function instead of the "=="
     operator to reduce the vulnerability to timing attacks.

HMAC.copy()

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

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

HMAC.digest_size

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

HMAC.block_size

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

   バージョン 3.4 で追加.

HMAC.name

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

   バージョン 3.4 で追加.

バージョン 3.10 で変更: Removed the undocumented attributes
"HMAC.digest_cons", "HMAC.inner", and "HMAC.outer".

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

hmac.compare_digest(a, b)

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

   注釈:

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

   バージョン 3.3 で追加.

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

参考:

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