diff options
| -rw-r--r-- | Doc/lib/libhashlib.tex | 114 |
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} |