1 files changed, 121 insertions, 0 deletions
diff --git a/Doc/library/hashlib.rst b/Doc/library/hashlib.rst
new file mode 100644
index 0000000000..f255554574
--- /dev/null
+++ b/Doc/library/hashlib.rst
@@ -0,0 +1,121 @@
+
+:mod:`hashlib` --- Secure hashes and message digests
+====================================================
+
+.. module:: hashlib
+   :synopsis: Secure hash and message digest algorithms.
+.. moduleauthor:: Gregory P. Smith <greg@users.sourceforge.net>
+.. sectionauthor:: Gregory P. Smith <greg@users.sourceforge.net>
+
+
+.. versionadded:: 2.5
+
+.. index::
+   single: message digest, MD5
+   single: secure hash algorithm, SHA1, SHA224, SHA256, SHA384, SHA512
+
+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.
+
+.. warning::
+
+   Some algorithms have known hash collision weaknesses, see the FAQ at the end.
+
+There is one constructor method named for each type of :dfn:`hash`.  All return
+a hash object with the same simple interface. For example: use :func:`sha1` to
+create a SHA1 hash object. You can now feed this object with arbitrary strings
+using the :meth:`update` method.  At any point you can ask it for the
+:dfn:`digest` of the concatenation of the strings fed to it so far using the
+:meth:`digest` or :meth:`hexdigest` methods.
+
+.. index:: single: OpenSSL
+
+Constructors for hash algorithms that are always present in this module are
+:func:`md5`, :func:`sha1`, :func:`sha224`, :func:`sha256`, :func:`sha384`, and
+:func:`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'
+
+More condensed::
+
+   >>> hashlib.sha224("Nobody inspects the spammish repetition").hexdigest()
+   'a4337bc45a8fc544c03f52dc550cd6e1e87021bc896588bd79e901e2'
+
+A generic :func:`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 :func:`new` and should be preferred.
+
+Using :func:`new` with an algorithm provided by OpenSSL::
+
+   >>> h = hashlib.new('ripemd160')
+   >>> h.update("Nobody inspects the spammish repetition")
+   >>> h.hexdigest()
+   'cc4a5ce1b3df48aec5d22d1f16b894a0b894eccc'
+
+The following values are provided as constant attributes of the hash objects
+returned by the constructors:
+
+
+.. data:: digest_size
+
+   The size of the resulting digest in bytes.
+
+A hash object has the following methods:
+
+
+.. method:: 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)``.
+
+
+.. method:: hash.digest()
+
+   Return the digest of the strings passed to the :meth:`update` method so far.
+   This is a string of :attr:`digest_size` bytes which may contain non-ASCII
+   characters, including null bytes.
+
+
+.. method:: hash.hexdigest()
+
+   Like :meth:`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.
+
+
+.. method:: 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.
+
+
+.. seealso::
+
+   Module :mod:`hmac`
+      A module to generate message authentication codes using hashes.
+
+   Module :mod:`base64`
+      Another way to encode binary hashes for non-binary environments.
+
+   http://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf
+      The FIPS 180-2 publication on Secure Hash Algorithms.
+
+   http://www.cryptography.com/cnews/hash.html
+      Hash Collision FAQ with information on which algorithms have known issues and
+      what that means regarding their use.
+