summaryrefslogtreecommitdiffstats
path: root/Doc
diff options
context:
space:
mode:
authorGregory P. Smith <greg@mad-scientist.com>2005-08-22 18:31:41 (GMT)
committerGregory P. Smith <greg@mad-scientist.com>2005-08-22 18:31:41 (GMT)
commit7208af47f8b1a34330194709e55e4ef17560cf6a (patch)
tree0cac4f584a5d1fb1d238bbdbc462fe919296bc8e /Doc
parentf0de6a18bb7b016a016dd58c49364ca63b965724 (diff)
downloadcpython-7208af47f8b1a34330194709e55e4ef17560cf6a.zip
cpython-7208af47f8b1a34330194709e55e4ef17560cf6a.tar.gz
cpython-7208af47f8b1a34330194709e55e4ef17560cf6a.tar.bz2
whoops, missed adding this last night in my hashlib commit
Diffstat (limited to 'Doc')
-rw-r--r--Doc/lib/libhashlib.tex114
1 files changed, 114 insertions, 0 deletions
diff --git a/Doc/lib/libhashlib.tex b/Doc/lib/libhashlib.tex
new file mode 100644
index 0000000..829849f
--- /dev/null
+++ b/Doc/lib/libhashlib.tex
@@ -0,0 +1,114 @@
+\section{\module{hashlib} ---
+ Secure hashes and message digests}
+
+\declaremodule{builtin}{hashlib}
+\modulesynopsis{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{message digest, MD5}
+\index{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 interchangable. 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 \function{sha1()} to create a SHA1 hash object.
+You can now feed this object with arbitrary strings using the \method{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 \method{digest()} or
+\method{hexdigest()} methods.
+
+Constructors for hash algorithms that are always present in this module are
+\function{md5()}, \function{sha1()}, \function{sha224()}, \function{sha256()},
+\function{sha384()}, and \function{sha512()}. Additional algorithms may also
+be available depending upon the OpenSSL library python uses on your platform.
+\index{OpenSSL}
+
+For example, to obtain the digest of the string \code{'Nobody inspects
+the spammish repetition'}:
+
+\begin{verbatim}
+>>> 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'
+\end{verbatim}
+
+More condensed:
+
+\begin{verbatim}
+>>> hashlib.sha224("Nobody inspects the spammish repetition").hexdigest()
+'a4337bc45a8fc544c03f52dc550cd6e1e87021bc896588bd79e901e2'
+\end{verbatim}
+
+A generic \function{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 \function{new()} and
+should be preferred.
+
+Using \function{new()} with an algorithm provided by OpenSSL:
+
+\begin{verbatim}
+>>> h = hashlib.new('ripemd160')
+>>> h.update("Nobody inspects the spammish repetition")
+>>> h.hexdigest()
+'cc4a5ce1b3df48aec5d22d1f16b894a0b894eccc'
+\end{verbatim}
+
+The following values are provided as constant attributes of the hash objects
+returned by the constructors:
+
+\begin{datadesc}{digest_size}
+ The size of the resulting digest in bytes.
+\end{datadesc}
+
+A hash object has the following methods:
+
+\begin{methoddesc}[hash]{update}{arg}
+Update the hash object with the string \var{arg}. Repeated calls are
+equivalent to a single call with the concatenation of all the
+arguments: \code{m.update(a); m.update(b)} is equivalent to
+\code{m.update(a+b)}.
+\end{methoddesc}
+
+\begin{methoddesc}[hash]{digest}{}
+Return the digest of the strings passed to the \method{update()}
+method so far. This is a 16-byte string which may contain
+non-\ASCII{} characters, including null bytes.
+\end{methoddesc}
+
+\begin{methoddesc}[hash]{hexdigest}{}
+Like \method{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.
+\end{methoddesc}
+
+\begin{methoddesc}[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.
+\end{methoddesc}
+
+\begin{seealso}
+ \seemodule{hmac}{A module to generate message authentication codes using hashes.}
+ \seemodule{base64}{Another way to encode binary hashes for non-binary environments.}
+ \seeurl{http://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf}
+ {The FIPS 180-2 publication on Secure Hash Algorithms.}
+ \seeurl{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.}
+\end{seealso}