"hashlib" — セキュアハッシュおよびメッセージダイジェスト
********************************************************

バージョン 2.5 で追加.

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

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

This module implements a common interface to many different secure
hash and message digest algorithms.  Included are the FIPS secure hash
algorithms SHA1, SHA224, SHA256, SHA384, and SHA512 (defined in FIPS
180-2) as well as RSA’s MD5 algorithm (defined in Internet **RFC
1321**). The terms secure hash and message digest are interchangeable.
Older algorithms were called message digests.  The modern term is
secure hash.

注釈: adler32 や crc32 ハッシュ関数は "zlib" モジュールで提供されて
  います 。

警告: 幾つかのアルゴリズムはハッシュの衝突に弱いことが知られています
  。最後 の 「参考」 セクションを見てください。

There is one constructor method named for each type of *hash*.  All
return a hash object with the same simple interface. For example: use
"sha1()" to create a SHA1 hash object. You can now feed this object
with arbitrary strings using the "update()" method.  At any point you
can ask it for the *digest* of the concatenation of the strings fed to
it so far using the "digest()" or "hexdigest()" methods.

Constructors for hash algorithms that are always present in this
module are "md5()", "sha1()", "sha224()", "sha256()", "sha384()", and
"sha512()".  Additional algorithms may also be available depending
upon the OpenSSL library that Python uses on your platform.

For example, to obtain the digest of the string "'Nobody inspects the
spammish repetition'":

>>> import hashlib
>>> m = hashlib.md5()
>>> m.update("Nobody inspects")
>>> m.update(" the spammish repetition")
>>> m.digest()
'\xbbd\x9c\x83\xdd\x1e\xa5\xc9\xd9\xde\xc9\xa1\x8d\xf0\xff\xe9'
>>> m.digest_size
16
>>> m.block_size
64

もっと簡潔に書くと、このようになります:

>>> hashlib.sha224("Nobody inspects the spammish repetition").hexdigest()
'a4337bc45a8fc544c03f52dc550cd6e1e87021bc896588bd79e901e2'

A generic "new()" constructor that takes the string name of the
desired algorithm as its first parameter also exists to allow access
to the above listed hashes as well as any other algorithms that your
OpenSSL library may offer.  The named constructors are much faster
than "new()" and should be preferred.

"new()" にOpenSSLのアルゴリズムを指定する例です:

>>> h = hashlib.new('ripemd160')
>>> h.update("Nobody inspects the spammish repetition")
>>> h.hexdigest()
'cc4a5ce1b3df48aec5d22d1f16b894a0b894eccc'

This module provides the following constant attribute:

hashlib.algorithms

   A tuple providing the names of the hash algorithms guaranteed to be
   supported by this module.

   バージョン 2.7 で追加.

hashlib.algorithms_guaranteed

   A set containing the names of the hash algorithms guaranteed to be
   supported by this module on all platforms.

   バージョン 2.7.9 で追加.

hashlib.algorithms_available

   実行中の Python インタープリタで利用可能なハッシュアルゴリズム名の
   set です。これらの名前は "new()" に渡すことができます。
   "algorithms_guaranteed" は常にサブセットです。この set の中に同じア
   ルゴリズムが違う名前で複数回現れることがあります (OpenSSL 由来)。

   バージョン 2.7.9 で追加.

コンストラクタが返すハッシュオブジェクトには、次のような定数属性が用意
されています:

hash.digest_size

   生成されたハッシュのバイト数。

hash.block_size

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

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

hash.update(arg)

   Update the hash object with the string *arg*.  Repeated calls are
   equivalent to a single call with the concatenation of all the
   arguments: "m.update(a); m.update(b)" is equivalent to
   "m.update(a+b)".

   バージョン 2.7 で変更: The Python GIL is released to allow other
   threads to run while hash updates on data larger than 2048 bytes is
   taking place when using hash algorithms supplied by OpenSSL.

hash.digest()

   Return the digest of the strings passed to the "update()" method so
   far. This is a string of "digest_size" bytes which may contain non-
   ASCII characters, including null bytes.

hash.hexdigest()

   Like "digest()" except the digest is returned as a string of double
   length, containing only hexadecimal digits.  This may  be used to
   exchange the value safely in email or other non-binary
   environments.

hash.copy()

   Return a copy (「clone」) of the hash object.  This can be used to
   efficiently compute the digests of strings that share a common
   initial substring.


鍵導出
======

鍵の導出 (derivation) と引き伸ばし (stretching) のアルゴリズムはセキュ
アなパスワードのハッシュ化のために設計されました。 "sha1(password)" の
ような甘いアルゴリズムは、ブルートフォース攻撃に抵抗できません。良いパ
スワードハッシュ化は調節可能で、遅くて、 salt を含まなければなりません
。

hashlib.pbkdf2_hmac(name, password, salt, rounds, dklen=None)

   この関数は PKCS#5 のパスワードに基づいた鍵導出関数 2 を提供していま
   す。疑似乱数関数として HMAC を使用しています。

   The string *name* is the desired name of the hash digest algorithm
   for HMAC, e.g. 『sha1』 or 『sha256』. *password* and *salt* are
   interpreted as buffers of bytes. Applications and libraries should
   limit *password* to a sensible value (e.g. 1024). *salt* should be
   about 16 or more bytes from a proper source, e.g. "os.urandom()".

   The number of *rounds* should be chosen based on the hash algorithm
   and computing power. As of 2013, at least 100,000 rounds of SHA-256
   is suggested.

   *dklen* is the length of the derived key. If *dklen* is "None" then
   the digest size of the hash algorithm *name* is used, e.g. 64 for
   SHA-512.

   >>> import hashlib, binascii
   >>> dk = hashlib.pbkdf2_hmac('sha256', b'password', b'salt', 100000)
   >>> binascii.hexlify(dk)
   b'0394a2ede332c9a13eb82e9b24631604c31df978b4e2f0fbd2c549944f9d79a5'

   バージョン 2.7.8 で追加.

   注釈: *pbkdf2_hmac* の高速な実装は OpenSSL 使用版で利用可能です。
     Python 実装は "hmac" のインラインバージョンを使います。それはおよ
     そ 3 倍 遅く、GIL を解放しません。

参考:

  "hmac" モジュール
     ハッシュを用いてメッセージ認証コードを生成するモジュールです。

  "base64" モジュール
     バイナリハッシュを非バイナリ環境用にエンコードするもうひとつの方
     法です。

  http://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf
     FIPS 180-2 のセキュアハッシュアルゴリズムについての説明。

  https://en.wikipedia.org/wiki/Cryptographic_hash_function#Cryptogra
  phic_hash_algorithms (日本語版: https://暗号学的ハッシュ関数)
     どのアルゴリズムにどんな既知の問題があって、それが実際に利用する
     際にどう影響するかについての Wikipedia の記事。
