• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# $Id$
2#
3#  Copyright (C) 2005   Gregory P. Smith (greg@krypto.org)
4#  Licensed to PSF under a Contributor Agreement.
5#
6
7__doc__ = """hashlib module - A common interface to many hash functions.
8
9new(name, string='') - returns a new hash object implementing the
10                       given hash function; initializing the hash
11                       using the given string data.
12
13Named constructor functions are also available, these are much faster
14than using new():
15
16md5(), sha1(), sha224(), sha256(), sha384(), and sha512()
17
18More algorithms may be available on your platform but the above are
19guaranteed to exist.
20
21NOTE: If you want the adler32 or crc32 hash functions they are available in
22the zlib module.
23
24Choose your hash function wisely.  Some have known collision weaknesses.
25sha384 and sha512 will be slow on 32 bit platforms.
26
27Hash objects have these methods:
28 - update(arg): Update the hash object with the string arg. Repeated calls
29                are equivalent to a single call with the concatenation of all
30                the arguments.
31 - digest():    Return the digest of the strings passed to the update() method
32                so far. This may contain non-ASCII characters, including
33                NUL bytes.
34 - hexdigest(): Like digest() except the digest is returned as a string of
35                double length, containing only hexadecimal digits.
36 - copy():      Return a copy (clone) of the hash object. This can be used to
37                efficiently compute the digests of strings that share a common
38                initial substring.
39
40For example, to obtain the digest of the string 'Nobody inspects the
41spammish repetition':
42
43    >>> import hashlib
44    >>> m = hashlib.md5()
45    >>> m.update("Nobody inspects")
46    >>> m.update(" the spammish repetition")
47    >>> m.digest()
48    '\\xbbd\\x9c\\x83\\xdd\\x1e\\xa5\\xc9\\xd9\\xde\\xc9\\xa1\\x8d\\xf0\\xff\\xe9'
49
50More condensed:
51
52    >>> hashlib.sha224("Nobody inspects the spammish repetition").hexdigest()
53    'a4337bc45a8fc544c03f52dc550cd6e1e87021bc896588bd79e901e2'
54
55"""
56
57# This tuple and __get_builtin_constructor() must be modified if a new
58# always available algorithm is added.
59__always_supported = ('md5', 'sha1', 'sha224', 'sha256', 'sha384', 'sha512')
60
61algorithms = __always_supported
62
63__all__ = __always_supported + ('new', 'algorithms')
64
65
66def __get_builtin_constructor(name):
67    try:
68        if name in ('SHA1', 'sha1'):
69            import _sha
70            return _sha.new
71        elif name in ('MD5', 'md5'):
72            import _md5
73            return _md5.new
74        elif name in ('SHA256', 'sha256', 'SHA224', 'sha224'):
75            import _sha256
76            bs = name[3:]
77            if bs == '256':
78                return _sha256.sha256
79            elif bs == '224':
80                return _sha256.sha224
81        elif name in ('SHA512', 'sha512', 'SHA384', 'sha384'):
82            import _sha512
83            bs = name[3:]
84            if bs == '512':
85                return _sha512.sha512
86            elif bs == '384':
87                return _sha512.sha384
88    except ImportError:
89        pass  # no extension module, this hash is unsupported.
90
91    raise ValueError('unsupported hash type %s' % name)
92
93
94def __get_openssl_constructor(name):
95    try:
96        f = getattr(_hashlib, 'openssl_' + name)
97        # Allow the C module to raise ValueError.  The function will be
98        # defined but the hash not actually available thanks to OpenSSL.
99        f()
100        # Use the C function directly (very fast)
101        return f
102    except (AttributeError, ValueError):
103        return __get_builtin_constructor(name)
104
105
106def __py_new(name, string=''):
107    """new(name, string='') - Return a new hashing object using the named algorithm;
108    optionally initialized with a string.
109    """
110    return __get_builtin_constructor(name)(string)
111
112
113def __hash_new(name, string=''):
114    """new(name, string='') - Return a new hashing object using the named algorithm;
115    optionally initialized with a string.
116    """
117    try:
118        return _hashlib.new(name, string)
119    except ValueError:
120        # If the _hashlib module (OpenSSL) doesn't support the named
121        # hash, try using our builtin implementations.
122        # This allows for SHA224/256 and SHA384/512 support even though
123        # the OpenSSL library prior to 0.9.8 doesn't provide them.
124        return __get_builtin_constructor(name)(string)
125
126
127try:
128    import _hashlib
129    new = __hash_new
130    __get_hash = __get_openssl_constructor
131except ImportError:
132    new = __py_new
133    __get_hash = __get_builtin_constructor
134
135for __func_name in __always_supported:
136    # try them all, some may not work due to the OpenSSL
137    # version not supporting that algorithm.
138    try:
139        globals()[__func_name] = __get_hash(__func_name)
140    except ValueError:
141        import logging
142        logging.exception('code for hash %s was not found.', __func_name)
143
144# Cleanup locals()
145del __always_supported, __func_name, __get_hash
146del __py_new, __hash_new, __get_openssl_constructor
147