Debian Codegraph @

Lib/test/support/hashlib_helper.py

raw
1 import functools
2 import hashlib
3 import importlib
4 import unittest
5 from test.support.import_helper import import_module
6
7 try:
8 import _hashlib
9 except ImportError:
10 _hashlib = None
11
12 try:
13 import _hmac
14 except ImportError:
15 _hmac = None
16
17
18 def requires_hashlib():
19 return unittest.skipIf(_hashlib is None, "requires _hashlib")
20
21
22 def requires_builtin_hmac():
23 return unittest.skipIf(_hmac is None, "requires _hmac")
24
25
26 def _missing_hash(digestname, implementation=None, *, exc=None):
27 parts = ["missing", implementation, f"hash algorithm: {digestname!r}"]
28 msg = " ".join(filter(None, parts))
29 raise unittest.SkipTest(msg) from exc
30
31
32 def _openssl_availabillity(digestname, *, usedforsecurity):
33 try:
34 _hashlib.new(digestname, usedforsecurity=usedforsecurity)
35 except AttributeError:
36 assert _hashlib is None
37 _missing_hash(digestname, "OpenSSL")
38 except ValueError as exc:
39 _missing_hash(digestname, "OpenSSL", exc=exc)
40
41
42 def _decorate_func_or_class(func_or_class, decorator_func):
43 if not isinstance(func_or_class, type):
44 return decorator_func(func_or_class)
45
46 decorated_class = func_or_class
47 setUpClass = decorated_class.__dict__.get('setUpClass')
48 if setUpClass is None:
49 def setUpClass(cls):
50 super(decorated_class, cls).setUpClass()
51 setUpClass.__qualname__ = decorated_class.__qualname__ + '.setUpClass'
52 setUpClass.__module__ = decorated_class.__module__
53 else:
54 setUpClass = setUpClass.__func__
55 setUpClass = classmethod(decorator_func(setUpClass))
56 decorated_class.setUpClass = setUpClass
57 return decorated_class
58
59
60 def requires_hashdigest(digestname, openssl=None, usedforsecurity=True):
61 """Decorator raising SkipTest if a hashing algorithm is not available.
62
63 The hashing algorithm may be missing, blocked by a strict crypto policy,
64 or Python may be configured with `--with-builtin-hashlib-hashes=no`.
65
66 If 'openssl' is True, then the decorator checks that OpenSSL provides
67 the algorithm. Otherwise the check falls back to (optional) built-in
68 HACL* implementations.
69
70 The usedforsecurity flag is passed to the constructor but has no effect
71 on HACL* implementations.
72
73 Examples of exceptions being suppressed:
74 ValueError: [digital envelope routines: EVP_DigestInit_ex] disabled for FIPS
75 ValueError: unsupported hash type md4
76 """
77 if openssl and _hashlib is not None:
78 def test_availability():
79 _hashlib.new(digestname, usedforsecurity=usedforsecurity)
80 else:
81 def test_availability():
82 hashlib.new(digestname, usedforsecurity=usedforsecurity)
83
84 def decorator_func(func):
85 @functools.wraps(func)
86 def wrapper(*args, **kwargs):
87 try:
88 test_availability()
89 except ValueError as exc:
90 _missing_hash(digestname, exc=exc)
91 return func(*args, **kwargs)
92 return wrapper
93
94 def decorator(func_or_class):
95 return _decorate_func_or_class(func_or_class, decorator_func)
96 return decorator
97
98
99 def requires_openssl_hashdigest(digestname, *, usedforsecurity=True):
100 """Decorator raising SkipTest if an OpenSSL hashing algorithm is missing.
101
102 The hashing algorithm may be missing or blocked by a strict crypto policy.
103 """
104 def decorator_func(func):
105 @requires_hashlib() # avoid checking at each call
106 @functools.wraps(func)
107 def wrapper(*args, **kwargs):
108 _openssl_availabillity(digestname, usedforsecurity=usedforsecurity)
109 return func(*args, **kwargs)
110 return wrapper
111
112 def decorator(func_or_class):
113 return _decorate_func_or_class(func_or_class, decorator_func)
114 return decorator
115
116
117 def find_openssl_hashdigest_constructor(digestname, *, usedforsecurity=True):
118 """Find the OpenSSL hash function constructor by its name."""
119 assert isinstance(digestname, str), digestname
120 _openssl_availabillity(digestname, usedforsecurity=usedforsecurity)
121 # This returns a function of the form _hashlib.openssl_<name> and
122 # not a lambda function as it is rejected by _hashlib.hmac_new().
123 return getattr(_hashlib, f"openssl_{digestname}")
124
125
126 def requires_builtin_hashdigest(
127 module_name, digestname, *, usedforsecurity=True
128 ):
129 """Decorator raising SkipTest if a HACL* hashing algorithm is missing.
130
131 - The *module_name* is the C extension module name based on HACL*.
132 - The *digestname* is one of its member, e.g., 'md5'.
133 """
134 def decorator_func(func):
135 @functools.wraps(func)
136 def wrapper(*args, **kwargs):
137 module = import_module(module_name)
138 try:
139 getattr(module, digestname)
140 except AttributeError:
141 fullname = f'{module_name}.{digestname}'
142 _missing_hash(fullname, implementation="HACL")
143 return func(*args, **kwargs)
144 return wrapper
145
146 def decorator(func_or_class):
147 return _decorate_func_or_class(func_or_class, decorator_func)
148 return decorator
149
150
151 def find_builtin_hashdigest_constructor(
152 module_name, digestname, *, usedforsecurity=True
153 ):
154 """Find the HACL* hash function constructor.
155
156 - The *module_name* is the C extension module name based on HACL*.
157 - The *digestname* is one of its member, e.g., 'md5'.
158 """
159 module = import_module(module_name)
160 try:
161 constructor = getattr(module, digestname)
162 constructor(b'', usedforsecurity=usedforsecurity)
163 except (AttributeError, TypeError, ValueError):
164 _missing_hash(f'{module_name}.{digestname}', implementation="HACL")
165 return constructor
166
167
168 class HashFunctionsTrait:
169 """Mixin trait class containing hash functions.
170
171 This class is assumed to have all unitest.TestCase methods but should
172 not directly inherit from it to prevent the test suite being run on it.
173
174 Subclasses should implement the hash functions by returning an object
175 that can be recognized as a valid digestmod parameter for both hashlib
176 and HMAC. In particular, it cannot be a lambda function as it will not
177 be recognized by hashlib (it will still be accepted by the pure Python
178 implementation of HMAC).
179 """
180
181 ALGORITHMS = [
182 'md5', 'sha1',
183 'sha224', 'sha256', 'sha384', 'sha512',
184 'sha3_224', 'sha3_256', 'sha3_384', 'sha3_512',
185 ]
186
187 # Default 'usedforsecurity' to use when looking up a hash function.
188 usedforsecurity = True
189
190 def _find_constructor(self, name):
191 # By default, a missing algorithm skips the test that uses it.
192 self.assertIn(name, self.ALGORITHMS)
193 self.skipTest(f"missing hash function: {name}")
194
195 @property
196 def md5(self):
197 return self._find_constructor("md5")
198
199 @property
200 def sha1(self):
201 return self._find_constructor("sha1")
202
203 @property
204 def sha224(self):
205 return self._find_constructor("sha224")
206
207 @property
208 def sha256(self):
209 return self._find_constructor("sha256")
210
211 @property
212 def sha384(self):
213 return self._find_constructor("sha384")
214
215 @property
216 def sha512(self):
217 return self._find_constructor("sha512")
218
219 @property
220 def sha3_224(self):
221 return self._find_constructor("sha3_224")
222
223 @property
224 def sha3_256(self):
225 return self._find_constructor("sha3_256")
226
227 @property
228 def sha3_384(self):
229 return self._find_constructor("sha3_384")
230
231 @property
232 def sha3_512(self):
233 return self._find_constructor("sha3_512")
234
235
236 class NamedHashFunctionsTrait(HashFunctionsTrait):
237 """Trait containing named hash functions.
238
239 Hash functions are available if and only if they are available in hashlib.
240 """
241
242 def _find_constructor(self, name):
243 self.assertIn(name, self.ALGORITHMS)
244 return name
245
246
247 class OpenSSLHashFunctionsTrait(HashFunctionsTrait):
248 """Trait containing OpenSSL hash functions.
249
250 Hash functions are available if and only if they are available in _hashlib.
251 """
252
253 def _find_constructor(self, name):
254 self.assertIn(name, self.ALGORITHMS)
255 return find_openssl_hashdigest_constructor(
256 name, usedforsecurity=self.usedforsecurity
257 )
258
259
260 class BuiltinHashFunctionsTrait(HashFunctionsTrait):
261 """Trait containing HACL* hash functions.
262
263 Hash functions are available if and only if they are available in C.
264 In particular, HACL* HMAC-MD5 may be available even though HACL* md5
265 is not since the former is unconditionally built.
266 """
267
268 def _find_constructor_in(self, module, name):
269 self.assertIn(name, self.ALGORITHMS)
270 return find_builtin_hashdigest_constructor(module, name)
271
272 @property
273 def md5(self):
274 return self._find_constructor_in("_md5", "md5")
275
276 @property
277 def sha1(self):
278 return self._find_constructor_in("_sha1", "sha1")
279
280 @property
281 def sha224(self):
282 return self._find_constructor_in("_sha2", "sha224")
283
284 @property
285 def sha256(self):
286 return self._find_constructor_in("_sha2", "sha256")
287
288 @property
289 def sha384(self):
290 return self._find_constructor_in("_sha2", "sha384")
291
292 @property
293 def sha512(self):
294 return self._find_constructor_in("_sha2", "sha512")
295
296 @property
297 def sha3_224(self):
298 return self._find_constructor_in("_sha3", "sha3_224")
299
300 @property
301 def sha3_256(self):
302 return self._find_constructor_in("_sha3","sha3_256")
303
304 @property
305 def sha3_384(self):
306 return self._find_constructor_in("_sha3","sha3_384")
307
308 @property
309 def sha3_512(self):
310 return self._find_constructor_in("_sha3","sha3_512")
311
312
313 def find_gil_minsize(modules_names, default=2048):
314 """Get the largest GIL_MINSIZE value for the given cryptographic modules.
315
316 The valid module names are the following:
317
318 - _hashlib
319 - _md5, _sha1, _sha2, _sha3, _blake2
320 - _hmac
321 """
322 sizes = []
323 for module_name in modules_names:
324 try:
325 module = importlib.import_module(module_name)
326 except ImportError:
327 continue
328 sizes.append(getattr(module, '_GIL_MINSIZE', default))
329 return max(sizes, default=default)