blob: d20e1f95a2afc8407ad6ea7b3602163f598e0896 [file] [log] [blame]
Gregory P. Smithf21a5f72005-08-21 18:45:59 +00001# $Id$
2#
Gregory P. Smithf8057852007-09-09 20:25:00 +00003# Copyright (C) 2005 Gregory P. Smith (greg@krypto.org)
Gregory P. Smithf21a5f72005-08-21 18:45:59 +00004# 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
Gregory P. Smithbde40072008-03-19 01:38:35 +000021NOTE: If you want the adler32 or crc32 hash functions they are available in
22the zlib module.
23
Georg Brandl7a4e8042006-10-29 18:01:08 +000024Choose your hash function wisely. Some have known collision weaknesses.
Gregory P. Smithf21a5f72005-08-21 18:45:59 +000025sha384 and sha512 will be slow on 32 bit platforms.
Georg Brandl7a4e8042006-10-29 18:01:08 +000026
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()
Gregory P. Smithf07e5a92008-08-31 16:34:18 +000048 '\\xbbd\\x9c\\x83\\xdd\\x1e\\xa5\\xc9\\xd9\\xde\\xc9\\xa1\\x8d\\xf0\\xff\\xe9'
Georg Brandl7a4e8042006-10-29 18:01:08 +000049
50More condensed:
51
52 >>> hashlib.sha224("Nobody inspects the spammish repetition").hexdigest()
53 'a4337bc45a8fc544c03f52dc550cd6e1e87021bc896588bd79e901e2'
54
Gregory P. Smithf21a5f72005-08-21 18:45:59 +000055"""
56
Gregory P. Smith99954c92009-08-16 21:54:45 +000057# 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
Gregory P. Smithe6390a12010-03-01 02:01:47 +000061algorithms = __always_supported
62
63__all__ = __always_supported + ('new', 'algorithms')
Gregory P. Smith99954c92009-08-16 21:54:45 +000064
Gregory P. Smithf21a5f72005-08-21 18:45:59 +000065
66def __get_builtin_constructor(name):
Gregory P. Smithfb1d60c2011-05-14 15:07:53 -070067 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.
Gregory P. Smithf21a5f72005-08-21 18:45:59 +000090
Gregory P. Smithb9e9e0d2012-07-21 21:22:16 -070091 raise ValueError('unsupported hash type ' + name)
Gregory P. Smith99954c92009-08-16 21:54:45 +000092
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)
Gregory P. Smithf21a5f72005-08-21 18:45:59 +0000104
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
Gregory P. Smithf21a5f72005-08-21 18:45:59 +0000129 new = __hash_new
Gregory P. Smith99954c92009-08-16 21:54:45 +0000130 __get_hash = __get_openssl_constructor
Gregory P. Smithf21a5f72005-08-21 18:45:59 +0000131except ImportError:
Gregory P. Smithf21a5f72005-08-21 18:45:59 +0000132 new = __py_new
Gregory P. Smith99954c92009-08-16 21:54:45 +0000133 __get_hash = __get_builtin_constructor
Gregory P. Smithf21a5f72005-08-21 18:45:59 +0000134
Gregory P. Smith99954c92009-08-16 21:54:45 +0000135for __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