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

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

======================================================================

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

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

   新しい hmac オブジェクトを返します。 *key* は秘密鍵を与える bytes
   または bytearray オブジェクトです。*msg* が与えられると、
   "update(msg)" が呼び出されます。*digestmod* は利用するダイジェスト
   名、ダイジェストコンストラクターまたは HMAC オブジェクトのモジュー
   ルです。"hashlib.new()" に与えることができる任意の名前をサポートし
   、デフォルトは "hashlib.md5" のコンストラクターです。

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

   バージョン 3.4 で非推奨: MD5  が *digestmod* の暗黙のデフォルトダイ
   ジェストとなるのは廃止予定です。

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 で追加.

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

hmac.compare_digest(a, b)

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

   注釈:

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

   バージョン 3.3 で追加.

参考:

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