mirror of
https://github.com/python/cpython.git
synced 2025-10-31 10:26:02 +00:00
114 lines
4.4 KiB
TeX
114 lines
4.4 KiB
TeX
\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 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 \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 that 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 string of \member{digest_size} bytes 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}
|