1 /* SHA3 module
2 *
3 * This module provides an interface to the SHA3 algorithm
4 *
5 * See below for information about the original code this module was
6 * based upon. Additional work performed by:
7 *
8 * Andrew Kuchling (amk@amk.ca)
9 * Greg Stein (gstein@lyra.org)
10 * Trevor Perrin (trevp@trevp.net)
11 * Gregory P. Smith (greg@krypto.org)
12 *
13 * Copyright (C) 2012-2022 Christian Heimes (christian@python.org)
14 * Licensed to PSF under a Contributor Agreement.
15 *
16 */
17
18 #ifndef Py_BUILD_CORE_BUILTIN
19 # define Py_BUILD_CORE_MODULE 1
20 #endif
21
22 #include "Python.h"
23 #include "pycore_strhex.h" // _Py_strhex()
24 #include "pycore_typeobject.h" // _PyType_GetModuleState()
25 #include "hashlib.h"
26
27 #define SHA3_MAX_DIGESTSIZE 64 /* 64 Bytes (512 Bits) for 224 to 512 */
28
29 typedef struct {
30 PyTypeObject *sha3_224_type;
31 PyTypeObject *sha3_256_type;
32 PyTypeObject *sha3_384_type;
33 PyTypeObject *sha3_512_type;
34 PyTypeObject *shake_128_type;
35 PyTypeObject *shake_256_type;
36 } SHA3State;
37
38 static inline SHA3State*
39 sha3_get_state(PyObject *module)
40 {
41 void *state = PyModule_GetState(module);
42 assert(state != NULL);
43 return (SHA3State *)state;
44 }
45
46 /*[clinic input]
47 module _sha3
48 class _sha3.sha3_224 "SHA3object *" "&SHA3_224typ"
49 class _sha3.sha3_256 "SHA3object *" "&SHA3_256typ"
50 class _sha3.sha3_384 "SHA3object *" "&SHA3_384typ"
51 class _sha3.sha3_512 "SHA3object *" "&SHA3_512typ"
52 class _sha3.shake_128 "SHA3object *" "&SHAKE128type"
53 class _sha3.shake_256 "SHA3object *" "&SHAKE256type"
54 [clinic start generated code]*/
55 /*[clinic end generated code: output=da39a3ee5e6b4b0d input=b8a53680f370285a]*/
56
57 /* The structure for storing SHA3 info */
58
59 #include "_hacl/Hacl_Hash_SHA3.h"
60
61 typedef struct {
62 PyObject_HEAD
63 // Prevents undefined behavior via multiple threads entering the C API.
64 // The lock will be NULL before threaded access has been enabled.
65 PyThread_type_lock lock;
66 Hacl_Streaming_Keccak_state *hash_state;
67 } SHA3object;
68
69 #include "clinic/sha3module.c.h"
70
71 static SHA3object *
72 newSHA3object(PyTypeObject *type)
73 {
74 SHA3object *newobj;
75 newobj = (SHA3object *)PyObject_New(SHA3object, type);
76 if (newobj == NULL) {
77 return NULL;
78 }
79 newobj->lock = NULL;
80 return newobj;
81 }
82
83 static void sha3_update(Hacl_Streaming_Keccak_state *state, uint8_t *buf, Py_ssize_t len) {
84 /* Note: we explicitly ignore the error code on the basis that it would take >
85 * 1 billion years to hash more than 2^64 bytes. */
86 #if PY_SSIZE_T_MAX > UINT32_MAX
87 while (len > UINT32_MAX) {
88 Hacl_Streaming_Keccak_update(state, buf, UINT32_MAX);
89 len -= UINT32_MAX;
90 buf += UINT32_MAX;
91 }
92 #endif
93 /* Cast to uint32_t is safe: len <= UINT32_MAX at this point. */
94 Hacl_Streaming_Keccak_update(state, buf, (uint32_t) len);
95 }
96
97 /*[clinic input]
98 @classmethod
99 _sha3.sha3_224.__new__ as py_sha3_new
100 data: object(c_default="NULL") = b''
101 /
102 *
103 usedforsecurity: bool = True
104
105 Return a new SHA3 hash object.
106 [clinic start generated code]*/
107
108 static PyObject *
109 py_sha3_new_impl(PyTypeObject *type, PyObject *data, int usedforsecurity)
110 /*[clinic end generated code: output=90409addc5d5e8b0 input=637e5f8f6a93982a]*/
111 {
112 Py_buffer buf = {NULL, NULL};
113 SHA3State *state = _PyType_GetModuleState(type);
114 SHA3object *self = newSHA3object(type);
115 if (self == NULL) {
116 goto error;
117 }
118
119 assert(state != NULL);
120
121 if (type == state->sha3_224_type) {
122 self->hash_state = Hacl_Streaming_Keccak_malloc(Spec_Hash_Definitions_SHA3_224);
123 } else if (type == state->sha3_256_type) {
124 self->hash_state = Hacl_Streaming_Keccak_malloc(Spec_Hash_Definitions_SHA3_256);
125 } else if (type == state->sha3_384_type) {
126 self->hash_state = Hacl_Streaming_Keccak_malloc(Spec_Hash_Definitions_SHA3_384);
127 } else if (type == state->sha3_512_type) {
128 self->hash_state = Hacl_Streaming_Keccak_malloc(Spec_Hash_Definitions_SHA3_512);
129 } else if (type == state->shake_128_type) {
130 self->hash_state = Hacl_Streaming_Keccak_malloc(Spec_Hash_Definitions_Shake128);
131 } else if (type == state->shake_256_type) {
132 self->hash_state = Hacl_Streaming_Keccak_malloc(Spec_Hash_Definitions_Shake256);
133 } else {
134 PyErr_BadInternalCall();
135 goto error;
136 }
137
138 if (data) {
139 GET_BUFFER_VIEW_OR_ERROR(data, &buf, goto error);
140 if (buf.len >= HASHLIB_GIL_MINSIZE) {
141 /* We do not initialize self->lock here as this is the constructor
142 * where it is not yet possible to have concurrent access. */
143 Py_BEGIN_ALLOW_THREADS
144 sha3_update(self->hash_state, buf.buf, buf.len);
145 Py_END_ALLOW_THREADS
146 } else {
147 sha3_update(self->hash_state, buf.buf, buf.len);
148 }
149 }
150
151 PyBuffer_Release(&buf);
152
153 return (PyObject *)self;
154
155 error:
156 if (self) {
157 Py_DECREF(self);
158 }
159 if (data && buf.obj) {
160 PyBuffer_Release(&buf);
161 }
162 return NULL;
163 }
164
165
166 /* Internal methods for a hash object */
167
168 static void
169 SHA3_dealloc(SHA3object *self)
170 {
171 Hacl_Streaming_Keccak_free(self->hash_state);
172 if (self->lock != NULL) {
173 PyThread_free_lock(self->lock);
174 }
175 PyTypeObject *tp = Py_TYPE(self);
176 PyObject_Free(self);
177 Py_DECREF(tp);
178 }
179
180
181 /* External methods for a hash object */
182
183
184 /*[clinic input]
185 _sha3.sha3_224.copy
186
187 Return a copy of the hash object.
188 [clinic start generated code]*/
189
190 static PyObject *
191 _sha3_sha3_224_copy_impl(SHA3object *self)
192 /*[clinic end generated code: output=6c537411ecdcda4c input=93a44aaebea51ba8]*/
193 {
194 SHA3object *newobj;
195
196 if ((newobj = newSHA3object(Py_TYPE(self))) == NULL) {
197 return NULL;
198 }
199 ENTER_HASHLIB(self);
200 newobj->hash_state = Hacl_Streaming_Keccak_copy(self->hash_state);
201 LEAVE_HASHLIB(self);
202 return (PyObject *)newobj;
203 }
204
205
206 /*[clinic input]
207 _sha3.sha3_224.digest
208
209 Return the digest value as a bytes object.
210 [clinic start generated code]*/
211
212 static PyObject *
213 _sha3_sha3_224_digest_impl(SHA3object *self)
214 /*[clinic end generated code: output=fd531842e20b2d5b input=5b2a659536bbd248]*/
215 {
216 unsigned char digest[SHA3_MAX_DIGESTSIZE];
217 // This function errors out if the algorithm is Shake. Here, we know this
218 // not to be the case, and therefore do not perform error checking.
219 ENTER_HASHLIB(self);
220 Hacl_Streaming_Keccak_finish(self->hash_state, digest);
221 LEAVE_HASHLIB(self);
222 return PyBytes_FromStringAndSize((const char *)digest,
223 Hacl_Streaming_Keccak_hash_len(self->hash_state));
224 }
225
226
227 /*[clinic input]
228 _sha3.sha3_224.hexdigest
229
230 Return the digest value as a string of hexadecimal digits.
231 [clinic start generated code]*/
232
233 static PyObject *
234 _sha3_sha3_224_hexdigest_impl(SHA3object *self)
235 /*[clinic end generated code: output=75ad03257906918d input=2d91bb6e0d114ee3]*/
236 {
237 unsigned char digest[SHA3_MAX_DIGESTSIZE];
238 ENTER_HASHLIB(self);
239 Hacl_Streaming_Keccak_finish(self->hash_state, digest);
240 LEAVE_HASHLIB(self);
241 return _Py_strhex((const char *)digest,
242 Hacl_Streaming_Keccak_hash_len(self->hash_state));
243 }
244
245
246 /*[clinic input]
247 _sha3.sha3_224.update
248
249 data: object
250 /
251
252 Update this hash object's state with the provided bytes-like object.
253 [clinic start generated code]*/
254
255 static PyObject *
256 _sha3_sha3_224_update(SHA3object *self, PyObject *data)
257 /*[clinic end generated code: output=d3223352286ed357 input=a887f54dcc4ae227]*/
258 {
259 Py_buffer buf;
260 GET_BUFFER_VIEW_OR_ERROUT(data, &buf);
261 if (self->lock == NULL && buf.len >= HASHLIB_GIL_MINSIZE) {
262 self->lock = PyThread_allocate_lock();
263 }
264 if (self->lock != NULL) {
265 Py_BEGIN_ALLOW_THREADS
266 PyThread_acquire_lock(self->lock, 1);
267 sha3_update(self->hash_state, buf.buf, buf.len);
268 PyThread_release_lock(self->lock);
269 Py_END_ALLOW_THREADS
270 } else {
271 sha3_update(self->hash_state, buf.buf, buf.len);
272 }
273 PyBuffer_Release(&buf);
274 Py_RETURN_NONE;
275 }
276
277
278 static PyMethodDef SHA3_methods[] = {
279 _SHA3_SHA3_224_COPY_METHODDEF
280 _SHA3_SHA3_224_DIGEST_METHODDEF
281 _SHA3_SHA3_224_HEXDIGEST_METHODDEF
282 _SHA3_SHA3_224_UPDATE_METHODDEF
283 {NULL, NULL} /* sentinel */
284 };
285
286
287 static PyObject *
288 SHA3_get_block_size(SHA3object *self, void *closure)
289 {
290 uint32_t rate = Hacl_Streaming_Keccak_block_len(self->hash_state);
291 return PyLong_FromLong(rate);
292 }
293
294
295 static PyObject *
296 SHA3_get_name(SHA3object *self, void *closure)
297 {
298 PyTypeObject *type = Py_TYPE(self);
299
300 SHA3State *state = _PyType_GetModuleState(type);
301 assert(state != NULL);
302
303 if (type == state->sha3_224_type) {
304 return PyUnicode_FromString("sha3_224");
305 } else if (type == state->sha3_256_type) {
306 return PyUnicode_FromString("sha3_256");
307 } else if (type == state->sha3_384_type) {
308 return PyUnicode_FromString("sha3_384");
309 } else if (type == state->sha3_512_type) {
310 return PyUnicode_FromString("sha3_512");
311 } else if (type == state->shake_128_type) {
312 return PyUnicode_FromString("shake_128");
313 } else if (type == state->shake_256_type) {
314 return PyUnicode_FromString("shake_256");
315 } else {
316 PyErr_BadInternalCall();
317 return NULL;
318 }
319 }
320
321
322 static PyObject *
323 SHA3_get_digest_size(SHA3object *self, void *closure)
324 {
325 // Preserving previous behavior: variable-length algorithms return 0
326 if (Hacl_Streaming_Keccak_is_shake(self->hash_state))
327 return PyLong_FromLong(0);
328 else
329 return PyLong_FromLong(Hacl_Streaming_Keccak_hash_len(self->hash_state));
330 }
331
332
333 static PyObject *
334 SHA3_get_capacity_bits(SHA3object *self, void *closure)
335 {
336 uint32_t rate = Hacl_Streaming_Keccak_block_len(self->hash_state) * 8;
337 int capacity = 1600 - rate;
338 return PyLong_FromLong(capacity);
339 }
340
341
342 static PyObject *
343 SHA3_get_rate_bits(SHA3object *self, void *closure)
344 {
345 uint32_t rate = Hacl_Streaming_Keccak_block_len(self->hash_state) * 8;
346 return PyLong_FromLong(rate);
347 }
348
349 static PyObject *
350 SHA3_get_suffix(SHA3object *self, void *closure)
351 {
352 unsigned char suffix[2] = {0x06, 0};
353 return PyBytes_FromStringAndSize((const char *)suffix, 1);
354 }
355
356 static PyGetSetDef SHA3_getseters[] = {
357 {"block_size", (getter)SHA3_get_block_size, NULL, NULL, NULL},
358 {"name", (getter)SHA3_get_name, NULL, NULL, NULL},
359 {"digest_size", (getter)SHA3_get_digest_size, NULL, NULL, NULL},
360 {"_capacity_bits", (getter)SHA3_get_capacity_bits, NULL, NULL, NULL},
361 {"_rate_bits", (getter)SHA3_get_rate_bits, NULL, NULL, NULL},
362 {"_suffix", (getter)SHA3_get_suffix, NULL, NULL, NULL},
363 {NULL} /* Sentinel */
364 };
365
366 #define SHA3_TYPE_SLOTS(type_slots_obj, type_doc, type_methods, type_getseters) \
367 static PyType_Slot type_slots_obj[] = { \
368 {Py_tp_dealloc, SHA3_dealloc}, \
369 {Py_tp_doc, (char*)type_doc}, \
370 {Py_tp_methods, type_methods}, \
371 {Py_tp_getset, type_getseters}, \
372 {Py_tp_new, py_sha3_new}, \
373 {0,0} \
374 }
375
376 // Using _PyType_GetModuleState() on these types is safe since they
377 // cannot be subclassed: it does not have the Py_TPFLAGS_BASETYPE flag.
378 #define SHA3_TYPE_SPEC(type_spec_obj, type_name, type_slots) \
379 static PyType_Spec type_spec_obj = { \
380 .name = "_sha3." type_name, \
381 .basicsize = sizeof(SHA3object), \
382 .flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_IMMUTABLETYPE, \
383 .slots = type_slots \
384 }
385
386 PyDoc_STRVAR(sha3_224__doc__,
387 "sha3_224([data], *, usedforsecurity=True) -> SHA3 object\n\
388 \n\
389 Return a new SHA3 hash object with a hashbit length of 28 bytes.");
390
391 PyDoc_STRVAR(sha3_256__doc__,
392 "sha3_256([data], *, usedforsecurity=True) -> SHA3 object\n\
393 \n\
394 Return a new SHA3 hash object with a hashbit length of 32 bytes.");
395
396 PyDoc_STRVAR(sha3_384__doc__,
397 "sha3_384([data], *, usedforsecurity=True) -> SHA3 object\n\
398 \n\
399 Return a new SHA3 hash object with a hashbit length of 48 bytes.");
400
401 PyDoc_STRVAR(sha3_512__doc__,
402 "sha3_512([data], *, usedforsecurity=True) -> SHA3 object\n\
403 \n\
404 Return a new SHA3 hash object with a hashbit length of 64 bytes.");
405
406 SHA3_TYPE_SLOTS(sha3_224_slots, sha3_224__doc__, SHA3_methods, SHA3_getseters);
407 SHA3_TYPE_SPEC(sha3_224_spec, "sha3_224", sha3_224_slots);
408
409 SHA3_TYPE_SLOTS(sha3_256_slots, sha3_256__doc__, SHA3_methods, SHA3_getseters);
410 SHA3_TYPE_SPEC(sha3_256_spec, "sha3_256", sha3_256_slots);
411
412 SHA3_TYPE_SLOTS(sha3_384_slots, sha3_384__doc__, SHA3_methods, SHA3_getseters);
413 SHA3_TYPE_SPEC(sha3_384_spec, "sha3_384", sha3_384_slots);
414
415 SHA3_TYPE_SLOTS(sha3_512_slots, sha3_512__doc__, SHA3_methods, SHA3_getseters);
416 SHA3_TYPE_SPEC(sha3_512_spec, "sha3_512", sha3_512_slots);
417
418 static PyObject *
419 _SHAKE_digest(SHA3object *self, unsigned long digestlen, int hex)
420 {
421 unsigned char *digest = NULL;
422 PyObject *result = NULL;
423
424 if (digestlen >= (1 << 29)) {
425 PyErr_SetString(PyExc_ValueError, "length is too large");
426 return NULL;
427 }
428 digest = (unsigned char*)PyMem_Malloc(digestlen);
429 if (digest == NULL) {
430 return PyErr_NoMemory();
431 }
432
433 /* Get the raw (binary) digest value. The HACL functions errors out if:
434 * - the algorith is not shake -- not the case here
435 * - the output length is zero -- we follow the existing behavior and return
436 * an empty digest, without raising an error */
437 if (digestlen > 0) {
438 Hacl_Streaming_Keccak_squeeze(self->hash_state, digest, digestlen);
439 }
440 if (hex) {
441 result = _Py_strhex((const char *)digest, digestlen);
442 } else {
443 result = PyBytes_FromStringAndSize((const char *)digest,
444 digestlen);
445 }
446 if (digest != NULL) {
447 PyMem_Free(digest);
448 }
449 return result;
450 }
451
452
453 /*[clinic input]
454 _sha3.shake_128.digest
455
456 length: unsigned_long
457 /
458
459 Return the digest value as a bytes object.
460 [clinic start generated code]*/
461
462 static PyObject *
463 _sha3_shake_128_digest_impl(SHA3object *self, unsigned long length)
464 /*[clinic end generated code: output=2313605e2f87bb8f input=418ef6a36d2e6082]*/
465 {
466 return _SHAKE_digest(self, length, 0);
467 }
468
469
470 /*[clinic input]
471 _sha3.shake_128.hexdigest
472
473 length: unsigned_long
474 /
475
476 Return the digest value as a string of hexadecimal digits.
477 [clinic start generated code]*/
478
479 static PyObject *
480 _sha3_shake_128_hexdigest_impl(SHA3object *self, unsigned long length)
481 /*[clinic end generated code: output=bf8e2f1e490944a8 input=69fb29b0926ae321]*/
482 {
483 return _SHAKE_digest(self, length, 1);
484 }
485
486 static PyObject *
487 SHAKE_get_digest_size(SHA3object *self, void *closure)
488 {
489 return PyLong_FromLong(0);
490 }
491
492 static PyObject *
493 SHAKE_get_suffix(SHA3object *self, void *closure)
494 {
495 unsigned char suffix[2] = {0x1f, 0};
496 return PyBytes_FromStringAndSize((const char *)suffix, 1);
497 }
498
499
500 static PyGetSetDef SHAKE_getseters[] = {
501 {"block_size", (getter)SHA3_get_block_size, NULL, NULL, NULL},
502 {"name", (getter)SHA3_get_name, NULL, NULL, NULL},
503 {"digest_size", (getter)SHAKE_get_digest_size, NULL, NULL, NULL},
504 {"_capacity_bits", (getter)SHA3_get_capacity_bits, NULL, NULL, NULL},
505 {"_rate_bits", (getter)SHA3_get_rate_bits, NULL, NULL, NULL},
506 {"_suffix", (getter)SHAKE_get_suffix, NULL, NULL, NULL},
507 {NULL} /* Sentinel */
508 };
509
510
511 static PyMethodDef SHAKE_methods[] = {
512 _SHA3_SHA3_224_COPY_METHODDEF
513 _SHA3_SHAKE_128_DIGEST_METHODDEF
514 _SHA3_SHAKE_128_HEXDIGEST_METHODDEF
515 _SHA3_SHA3_224_UPDATE_METHODDEF
516 {NULL, NULL} /* sentinel */
517 };
518
519 PyDoc_STRVAR(shake_128__doc__,
520 "shake_128([data], *, usedforsecurity=True) -> SHAKE object\n\
521 \n\
522 Return a new SHAKE hash object.");
523
524 PyDoc_STRVAR(shake_256__doc__,
525 "shake_256([data], *, usedforsecurity=True) -> SHAKE object\n\
526 \n\
527 Return a new SHAKE hash object.");
528
529 SHA3_TYPE_SLOTS(SHAKE128slots, shake_128__doc__, SHAKE_methods, SHAKE_getseters);
530 SHA3_TYPE_SPEC(SHAKE128_spec, "shake_128", SHAKE128slots);
531
532 SHA3_TYPE_SLOTS(SHAKE256slots, shake_256__doc__, SHAKE_methods, SHAKE_getseters);
533 SHA3_TYPE_SPEC(SHAKE256_spec, "shake_256", SHAKE256slots);
534
535
536 static int
537 _sha3_traverse(PyObject *module, visitproc visit, void *arg)
538 {
539 SHA3State *state = sha3_get_state(module);
540 Py_VISIT(state->sha3_224_type);
541 Py_VISIT(state->sha3_256_type);
542 Py_VISIT(state->sha3_384_type);
543 Py_VISIT(state->sha3_512_type);
544 Py_VISIT(state->shake_128_type);
545 Py_VISIT(state->shake_256_type);
546 return 0;
547 }
548
549 static int
550 _sha3_clear(PyObject *module)
551 {
552 SHA3State *state = sha3_get_state(module);
553 Py_CLEAR(state->sha3_224_type);
554 Py_CLEAR(state->sha3_256_type);
555 Py_CLEAR(state->sha3_384_type);
556 Py_CLEAR(state->sha3_512_type);
557 Py_CLEAR(state->shake_128_type);
558 Py_CLEAR(state->shake_256_type);
559 return 0;
560 }
561
562 static void
563 _sha3_free(void *module)
564 {
565 _sha3_clear((PyObject *)module);
566 }
567
568 static int
569 _sha3_exec(PyObject *m)
570 {
571 SHA3State *st = sha3_get_state(m);
572
573 #define init_sha3type(type, typespec) \
574 do { \
575 st->type = (PyTypeObject *)PyType_FromModuleAndSpec( \
576 m, &typespec, NULL); \
577 if (st->type == NULL) { \
578 return -1; \
579 } \
580 if (PyModule_AddType(m, st->type) < 0) { \
581 return -1; \
582 } \
583 } while(0)
584
585 init_sha3type(sha3_224_type, sha3_224_spec);
586 init_sha3type(sha3_256_type, sha3_256_spec);
587 init_sha3type(sha3_384_type, sha3_384_spec);
588 init_sha3type(sha3_512_type, sha3_512_spec);
589 init_sha3type(shake_128_type, SHAKE128_spec);
590 init_sha3type(shake_256_type, SHAKE256_spec);
591 #undef init_sha3type
592
593 if (PyModule_AddStringConstant(m, "implementation",
594 "HACL") < 0) {
595 return -1;
596 }
597
598 return 0;
599 }
600
601 static PyModuleDef_Slot _sha3_slots[] = {
602 {Py_mod_exec, _sha3_exec},
603 {Py_mod_multiple_interpreters, Py_MOD_PER_INTERPRETER_GIL_SUPPORTED},
604 {0, NULL}
605 };
606
607 /* Initialize this module. */
608 static struct PyModuleDef _sha3module = {
609 PyModuleDef_HEAD_INIT,
610 .m_name = "_sha3",
611 .m_size = sizeof(SHA3State),
612 .m_slots = _sha3_slots,
613 .m_traverse = _sha3_traverse,
614 .m_clear = _sha3_clear,
615 .m_free = _sha3_free,
616 };
617
618
619 PyMODINIT_FUNC
620 PyInit__sha3(void)
621 {
622 return PyModuleDef_Init(&_sha3module);
623 }