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