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 "../hashlib.h"
25
26#include "sha3.c"
27
28#define SHA3_MAX_DIGESTSIZE 64 /* 64 Bytes (512 Bits) for 224 to 512 */
29#define SHA3_LANESIZE 0
30#define SHA3_state sha3_ctx_t
31#define SHA3_init sha3_init
32#define SHA3_process sha3_update
33#define SHA3_done(state, digest) sha3_final(digest, state)
34#define SHA3_squeeze(state, out, len) shake_xof(state), shake_out(state, out, len)
35#define SHA3_copystate(dest, src) memcpy(&(dest), &(src), sizeof(SHA3_state))
36
37// no optimization
38#define KeccakOpt 0
39
40typedef enum { SUCCESS = 1, FAIL = 0, BAD_HASHLEN = 2 } HashReturn;
41
42typedef struct {
43    PyTypeObject *sha3_224_type;
44    PyTypeObject *sha3_256_type;
45    PyTypeObject *sha3_384_type;
46    PyTypeObject *sha3_512_type;
47    PyTypeObject *shake_128_type;
48    PyTypeObject *shake_256_type;
49} SHA3State;
50
51static inline SHA3State*
52sha3_get_state(PyObject *module)
53{
54    void *state = PyModule_GetState(module);
55    assert(state != NULL);
56    return (SHA3State *)state;
57}
58
59/*[clinic input]
60module _sha3
61class _sha3.sha3_224 "SHA3object *" "&SHA3_224typ"
62class _sha3.sha3_256 "SHA3object *" "&SHA3_256typ"
63class _sha3.sha3_384 "SHA3object *" "&SHA3_384typ"
64class _sha3.sha3_512 "SHA3object *" "&SHA3_512typ"
65class _sha3.shake_128 "SHA3object *" "&SHAKE128type"
66class _sha3.shake_256 "SHA3object *" "&SHAKE256type"
67[clinic start generated code]*/
68/*[clinic end generated code: output=da39a3ee5e6b4b0d input=b8a53680f370285a]*/
69
70/* The structure for storing SHA3 info */
71
72typedef struct {
73    PyObject_HEAD
74    SHA3_state hash_state;
75    PyThread_type_lock lock;
76} SHA3object;
77
78#include "clinic/sha3module.c.h"
79
80static SHA3object *
81newSHA3object(PyTypeObject *type)
82{
83    SHA3object *newobj;
84    newobj = (SHA3object *)PyObject_New(SHA3object, type);
85    if (newobj == NULL) {
86        return NULL;
87    }
88    newobj->lock = NULL;
89    return newobj;
90}
91
92/*[clinic input]
93@classmethod
94_sha3.sha3_224.__new__ as py_sha3_new
95    data: object(c_default="NULL") = b''
96    /
97    *
98    usedforsecurity: bool = True
99
100Return a new BLAKE2b hash object.
101[clinic start generated code]*/
102
103static PyObject *
104py_sha3_new_impl(PyTypeObject *type, PyObject *data, int usedforsecurity)
105/*[clinic end generated code: output=90409addc5d5e8b0 input=bcfcdf2e4368347a]*/
106{
107    HashReturn res;
108    Py_buffer buf = {NULL, NULL};
109    SHA3State *state = PyType_GetModuleState(type);
110    SHA3object *self = newSHA3object(type);
111    if (self == NULL) {
112        goto error;
113    }
114
115    assert(state != NULL);
116
117    if (type == state->sha3_224_type) {
118        res = sha3_init(&self->hash_state, 28);
119    } else if (type == state->sha3_256_type) {
120        res = sha3_init(&self->hash_state, 32);
121    } else if (type == state->sha3_384_type) {
122        res = sha3_init(&self->hash_state, 48);
123    } else if (type == state->sha3_512_type) {
124        res = sha3_init(&self->hash_state, 64);
125    } else if (type == state->shake_128_type) {
126        res = sha3_init(&self->hash_state, 16);
127    } else if (type == state->shake_256_type) {
128        res = sha3_init(&self->hash_state, 32);
129    } else {
130        PyErr_BadInternalCall();
131        goto error;
132    }
133
134    if (res != SUCCESS) {
135        PyErr_SetString(PyExc_RuntimeError,
136                        "internal error in SHA3 initialize()");
137        goto error;
138    }
139
140    if (data) {
141        GET_BUFFER_VIEW_OR_ERROR(data, &buf, goto error);
142        if (buf.len >= HASHLIB_GIL_MINSIZE) {
143            /* invariant: New objects can't be accessed by other code yet,
144             * thus it's safe to release the GIL without locking the object.
145             */
146            Py_BEGIN_ALLOW_THREADS
147            res = SHA3_process(&self->hash_state, buf.buf, buf.len);
148            Py_END_ALLOW_THREADS
149        }
150        else {
151            res = SHA3_process(&self->hash_state, buf.buf, buf.len);
152        }
153        if (res != SUCCESS) {
154            PyErr_SetString(PyExc_RuntimeError,
155                            "internal error in SHA3 Update()");
156            goto error;
157        }
158        PyBuffer_Release(&buf);
159    }
160
161    return (PyObject *)self;
162
163  error:
164    if (self) {
165        Py_DECREF(self);
166    }
167    if (data && buf.obj) {
168        PyBuffer_Release(&buf);
169    }
170    return NULL;
171}
172
173
174/* Internal methods for a hash object */
175
176static void
177SHA3_dealloc(SHA3object *self)
178{
179    if (self->lock) {
180        PyThread_free_lock(self->lock);
181    }
182
183    PyTypeObject *tp = Py_TYPE(self);
184    PyObject_Free(self);
185    Py_DECREF(tp);
186}
187
188
189/* External methods for a hash object */
190
191
192/*[clinic input]
193_sha3.sha3_224.copy
194
195Return a copy of the hash object.
196[clinic start generated code]*/
197
198static PyObject *
199_sha3_sha3_224_copy_impl(SHA3object *self)
200/*[clinic end generated code: output=6c537411ecdcda4c input=93a44aaebea51ba8]*/
201{
202    SHA3object *newobj;
203
204    if ((newobj = newSHA3object(Py_TYPE(self))) == NULL) {
205        return NULL;
206    }
207    ENTER_HASHLIB(self);
208    SHA3_copystate(newobj->hash_state, self->hash_state);
209    LEAVE_HASHLIB(self);
210    return (PyObject *)newobj;
211}
212
213
214/*[clinic input]
215_sha3.sha3_224.digest
216
217Return the digest value as a bytes object.
218[clinic start generated code]*/
219
220static PyObject *
221_sha3_sha3_224_digest_impl(SHA3object *self)
222/*[clinic end generated code: output=fd531842e20b2d5b input=5b2a659536bbd248]*/
223{
224    unsigned char digest[SHA3_MAX_DIGESTSIZE + SHA3_LANESIZE];
225    SHA3_state temp;
226    HashReturn res;
227
228    ENTER_HASHLIB(self);
229    SHA3_copystate(temp, self->hash_state);
230    LEAVE_HASHLIB(self);
231    res = SHA3_done(&temp, digest);
232    if (res != SUCCESS) {
233        PyErr_SetString(PyExc_RuntimeError, "internal error in SHA3 Final()");
234        return NULL;
235    }
236    return PyBytes_FromStringAndSize((const char *)digest,
237                                      self->hash_state.mdlen);
238}
239
240
241/*[clinic input]
242_sha3.sha3_224.hexdigest
243
244Return the digest value as a string of hexadecimal digits.
245[clinic start generated code]*/
246
247static PyObject *
248_sha3_sha3_224_hexdigest_impl(SHA3object *self)
249/*[clinic end generated code: output=75ad03257906918d input=2d91bb6e0d114ee3]*/
250{
251    unsigned char digest[SHA3_MAX_DIGESTSIZE + SHA3_LANESIZE];
252    SHA3_state temp;
253    HashReturn res;
254
255    /* Get the raw (binary) digest value */
256    ENTER_HASHLIB(self);
257    SHA3_copystate(temp, self->hash_state);
258    LEAVE_HASHLIB(self);
259    res = SHA3_done(&temp, digest);
260    if (res != SUCCESS) {
261        PyErr_SetString(PyExc_RuntimeError, "internal error in SHA3 Final()");
262        return NULL;
263    }
264    return _Py_strhex((const char *)digest,
265                      self->hash_state.mdlen);
266}
267
268
269/*[clinic input]
270_sha3.sha3_224.update
271
272    data: object
273    /
274
275Update this hash object's state with the provided bytes-like object.
276[clinic start generated code]*/
277
278static PyObject *
279_sha3_sha3_224_update(SHA3object *self, PyObject *data)
280/*[clinic end generated code: output=d3223352286ed357 input=a887f54dcc4ae227]*/
281{
282    Py_buffer buf;
283    HashReturn res;
284
285    GET_BUFFER_VIEW_OR_ERROUT(data, &buf);
286
287    /* add new data, the function takes the length in bits not bytes */
288    if (self->lock == NULL && buf.len >= HASHLIB_GIL_MINSIZE) {
289        self->lock = PyThread_allocate_lock();
290    }
291    /* Once a lock exists all code paths must be synchronized. We have to
292     * release the GIL even for small buffers as acquiring the lock may take
293     * an unlimited amount of time when another thread updates this object
294     * with lots of data. */
295    if (self->lock) {
296        Py_BEGIN_ALLOW_THREADS
297        PyThread_acquire_lock(self->lock, 1);
298        res = SHA3_process(&self->hash_state, buf.buf, buf.len);
299        PyThread_release_lock(self->lock);
300        Py_END_ALLOW_THREADS
301    }
302    else {
303        res = SHA3_process(&self->hash_state, buf.buf, buf.len);
304    }
305
306    if (res != SUCCESS) {
307        PyBuffer_Release(&buf);
308        PyErr_SetString(PyExc_RuntimeError,
309                        "internal error in SHA3 Update()");
310        return NULL;
311    }
312
313    PyBuffer_Release(&buf);
314    Py_RETURN_NONE;
315}
316
317
318static PyMethodDef SHA3_methods[] = {
319    _SHA3_SHA3_224_COPY_METHODDEF
320    _SHA3_SHA3_224_DIGEST_METHODDEF
321    _SHA3_SHA3_224_HEXDIGEST_METHODDEF
322    _SHA3_SHA3_224_UPDATE_METHODDEF
323    {NULL,        NULL}         /* sentinel */
324};
325
326
327static PyObject *
328SHA3_get_block_size(SHA3object *self, void *closure)
329{
330    int rate = self->hash_state.rsiz;
331    return PyLong_FromLong(rate);
332}
333
334
335static PyObject *
336SHA3_get_name(SHA3object *self, void *closure)
337{
338    PyTypeObject *type = Py_TYPE(self);
339
340    SHA3State *state = PyType_GetModuleState(type);
341    assert(state != NULL);
342
343    if (type == state->sha3_224_type) {
344        return PyUnicode_FromString("sha3_224");
345    } else if (type == state->sha3_256_type) {
346        return PyUnicode_FromString("sha3_256");
347    } else if (type == state->sha3_384_type) {
348        return PyUnicode_FromString("sha3_384");
349    } else if (type == state->sha3_512_type) {
350        return PyUnicode_FromString("sha3_512");
351    } else if (type == state->shake_128_type) {
352        return PyUnicode_FromString("shake_128");
353    } else if (type == state->shake_256_type) {
354        return PyUnicode_FromString("shake_256");
355    } else {
356        PyErr_BadInternalCall();
357        return NULL;
358    }
359}
360
361
362static PyObject *
363SHA3_get_digest_size(SHA3object *self, void *closure)
364{
365    return PyLong_FromLong(self->hash_state.mdlen);
366}
367
368
369static PyObject *
370SHA3_get_capacity_bits(SHA3object *self, void *closure)
371{
372    int capacity = 1600 - self->hash_state.rsiz * 8;
373    return PyLong_FromLong(capacity);
374}
375
376
377static PyObject *
378SHA3_get_rate_bits(SHA3object *self, void *closure)
379{
380    unsigned int rate = self->hash_state.rsiz * 8;
381    return PyLong_FromLong(rate);
382}
383
384static PyObject *
385SHA3_get_suffix(SHA3object *self, void *closure)
386{
387    unsigned char suffix[2] = {0x06, 0};
388    return PyBytes_FromStringAndSize((const char *)suffix, 1);
389}
390
391static PyGetSetDef SHA3_getseters[] = {
392    {"block_size", (getter)SHA3_get_block_size, NULL, NULL, NULL},
393    {"name", (getter)SHA3_get_name, NULL, NULL, NULL},
394    {"digest_size", (getter)SHA3_get_digest_size, NULL, NULL, NULL},
395    {"_capacity_bits", (getter)SHA3_get_capacity_bits, NULL, NULL, NULL},
396    {"_rate_bits", (getter)SHA3_get_rate_bits, NULL, NULL, NULL},
397    {"_suffix", (getter)SHA3_get_suffix, NULL, NULL, NULL},
398    {NULL}  /* Sentinel */
399};
400
401#define SHA3_TYPE_SLOTS(type_slots_obj, type_doc, type_methods, type_getseters) \
402    static PyType_Slot type_slots_obj[] = { \
403        {Py_tp_dealloc, SHA3_dealloc}, \
404        {Py_tp_doc, (char*)type_doc}, \
405        {Py_tp_methods, type_methods}, \
406        {Py_tp_getset, type_getseters}, \
407        {Py_tp_new, py_sha3_new}, \
408        {0,0} \
409    }
410
411// Using PyType_GetModuleState() on these types is safe since they
412// cannot be subclassed: it does not have the Py_TPFLAGS_BASETYPE flag.
413#define SHA3_TYPE_SPEC(type_spec_obj, type_name, type_slots) \
414    static PyType_Spec type_spec_obj = { \
415        .name = "_sha3." type_name, \
416        .basicsize = sizeof(SHA3object), \
417        .flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_IMMUTABLETYPE, \
418        .slots = type_slots \
419    }
420
421PyDoc_STRVAR(sha3_224__doc__,
422"sha3_224([data], *, usedforsecurity=True) -> SHA3 object\n\
423\n\
424Return a new SHA3 hash object with a hashbit length of 28 bytes.");
425
426PyDoc_STRVAR(sha3_256__doc__,
427"sha3_256([data], *, usedforsecurity=True) -> SHA3 object\n\
428\n\
429Return a new SHA3 hash object with a hashbit length of 32 bytes.");
430
431PyDoc_STRVAR(sha3_384__doc__,
432"sha3_384([data], *, usedforsecurity=True) -> SHA3 object\n\
433\n\
434Return a new SHA3 hash object with a hashbit length of 48 bytes.");
435
436PyDoc_STRVAR(sha3_512__doc__,
437"sha3_512([data], *, usedforsecurity=True) -> SHA3 object\n\
438\n\
439Return a new SHA3 hash object with a hashbit length of 64 bytes.");
440
441SHA3_TYPE_SLOTS(sha3_224_slots, sha3_224__doc__, SHA3_methods, SHA3_getseters);
442SHA3_TYPE_SPEC(sha3_224_spec, "sha3_224", sha3_224_slots);
443
444SHA3_TYPE_SLOTS(sha3_256_slots, sha3_256__doc__, SHA3_methods, SHA3_getseters);
445SHA3_TYPE_SPEC(sha3_256_spec, "sha3_256", sha3_256_slots);
446
447SHA3_TYPE_SLOTS(sha3_384_slots, sha3_384__doc__, SHA3_methods, SHA3_getseters);
448SHA3_TYPE_SPEC(sha3_384_spec, "sha3_384", sha3_384_slots);
449
450SHA3_TYPE_SLOTS(sha3_512_slots, sha3_512__doc__, SHA3_methods, SHA3_getseters);
451SHA3_TYPE_SPEC(sha3_512_spec, "sha3_512", sha3_512_slots);
452
453static PyObject *
454_SHAKE_digest(SHA3object *self, unsigned long digestlen, int hex)
455{
456    unsigned char *digest = NULL;
457    SHA3_state temp;
458    PyObject *result = NULL;
459
460    if (digestlen >= (1 << 29)) {
461        PyErr_SetString(PyExc_ValueError, "length is too large");
462        return NULL;
463    }
464    /* ExtractLane needs at least SHA3_MAX_DIGESTSIZE + SHA3_LANESIZE and
465     * SHA3_LANESIZE extra space.
466     */
467    digest = (unsigned char*)PyMem_Malloc(digestlen + SHA3_LANESIZE);
468    if (digest == NULL) {
469        return PyErr_NoMemory();
470    }
471
472    /* Get the raw (binary) digest value */
473    ENTER_HASHLIB(self);
474    SHA3_copystate(temp, self->hash_state);
475    LEAVE_HASHLIB(self);
476    SHA3_squeeze(&temp, digest, digestlen);
477    if (hex) {
478         result = _Py_strhex((const char *)digest, digestlen);
479    } else {
480        result = PyBytes_FromStringAndSize((const char *)digest,
481                                           digestlen);
482    }
483    if (digest != NULL) {
484        PyMem_Free(digest);
485    }
486    return result;
487}
488
489
490/*[clinic input]
491_sha3.shake_128.digest
492
493    length: unsigned_long
494    /
495
496Return the digest value as a bytes object.
497[clinic start generated code]*/
498
499static PyObject *
500_sha3_shake_128_digest_impl(SHA3object *self, unsigned long length)
501/*[clinic end generated code: output=2313605e2f87bb8f input=418ef6a36d2e6082]*/
502{
503    return _SHAKE_digest(self, length, 0);
504}
505
506
507/*[clinic input]
508_sha3.shake_128.hexdigest
509
510    length: unsigned_long
511    /
512
513Return the digest value as a string of hexadecimal digits.
514[clinic start generated code]*/
515
516static PyObject *
517_sha3_shake_128_hexdigest_impl(SHA3object *self, unsigned long length)
518/*[clinic end generated code: output=bf8e2f1e490944a8 input=69fb29b0926ae321]*/
519{
520    return _SHAKE_digest(self, length, 1);
521}
522
523static PyObject *
524SHAKE_get_digest_size(SHA3object *self, void *closure)
525{
526    return PyLong_FromLong(0);
527}
528
529static PyObject *
530SHAKE_get_suffix(SHA3object *self, void *closure)
531{
532    unsigned char suffix[2] = {0x1f, 0};
533    return PyBytes_FromStringAndSize((const char *)suffix, 1);
534}
535
536
537static PyGetSetDef SHAKE_getseters[] = {
538    {"block_size", (getter)SHA3_get_block_size, NULL, NULL, NULL},
539    {"name", (getter)SHA3_get_name, NULL, NULL, NULL},
540    {"digest_size", (getter)SHAKE_get_digest_size, NULL, NULL, NULL},
541    {"_capacity_bits", (getter)SHA3_get_capacity_bits, NULL, NULL, NULL},
542    {"_rate_bits", (getter)SHA3_get_rate_bits, NULL, NULL, NULL},
543    {"_suffix", (getter)SHAKE_get_suffix, NULL, NULL, NULL},
544    {NULL}  /* Sentinel */
545};
546
547
548static PyMethodDef SHAKE_methods[] = {
549    _SHA3_SHA3_224_COPY_METHODDEF
550    _SHA3_SHAKE_128_DIGEST_METHODDEF
551    _SHA3_SHAKE_128_HEXDIGEST_METHODDEF
552    _SHA3_SHA3_224_UPDATE_METHODDEF
553    {NULL,        NULL}         /* sentinel */
554};
555
556PyDoc_STRVAR(shake_128__doc__,
557"shake_128([data], *, usedforsecurity=True) -> SHAKE object\n\
558\n\
559Return a new SHAKE hash object.");
560
561PyDoc_STRVAR(shake_256__doc__,
562"shake_256([data], *, usedforsecurity=True) -> SHAKE object\n\
563\n\
564Return a new SHAKE hash object.");
565
566SHA3_TYPE_SLOTS(SHAKE128slots, shake_128__doc__, SHAKE_methods, SHAKE_getseters);
567SHA3_TYPE_SPEC(SHAKE128_spec, "shake_128", SHAKE128slots);
568
569SHA3_TYPE_SLOTS(SHAKE256slots, shake_256__doc__, SHAKE_methods, SHAKE_getseters);
570SHA3_TYPE_SPEC(SHAKE256_spec, "shake_256", SHAKE256slots);
571
572
573static int
574_sha3_traverse(PyObject *module, visitproc visit, void *arg)
575{
576    SHA3State *state = sha3_get_state(module);
577    Py_VISIT(state->sha3_224_type);
578    Py_VISIT(state->sha3_256_type);
579    Py_VISIT(state->sha3_384_type);
580    Py_VISIT(state->sha3_512_type);
581    Py_VISIT(state->shake_128_type);
582    Py_VISIT(state->shake_256_type);
583    return 0;
584}
585
586static int
587_sha3_clear(PyObject *module)
588{
589    SHA3State *state = sha3_get_state(module);
590    Py_CLEAR(state->sha3_224_type);
591    Py_CLEAR(state->sha3_256_type);
592    Py_CLEAR(state->sha3_384_type);
593    Py_CLEAR(state->sha3_512_type);
594    Py_CLEAR(state->shake_128_type);
595    Py_CLEAR(state->shake_256_type);
596    return 0;
597}
598
599static void
600_sha3_free(void *module)
601{
602    _sha3_clear((PyObject *)module);
603}
604
605static int
606_sha3_exec(PyObject *m)
607{
608    SHA3State *st = sha3_get_state(m);
609
610#define init_sha3type(type, typespec)                           \
611    do {                                                        \
612        st->type = (PyTypeObject *)PyType_FromModuleAndSpec(    \
613            m, &typespec, NULL);                                \
614        if (st->type == NULL) {                                 \
615            return -1;                                          \
616        }                                                       \
617        if (PyModule_AddType(m, st->type) < 0) {                \
618            return -1;                                          \
619        }                                                       \
620    } while(0)
621
622    init_sha3type(sha3_224_type, sha3_224_spec);
623    init_sha3type(sha3_256_type, sha3_256_spec);
624    init_sha3type(sha3_384_type, sha3_384_spec);
625    init_sha3type(sha3_512_type, sha3_512_spec);
626    init_sha3type(shake_128_type, SHAKE128_spec);
627    init_sha3type(shake_256_type, SHAKE256_spec);
628#undef init_sha3type
629
630    if (PyModule_AddIntConstant(m, "keccakopt", KeccakOpt) < 0) {
631        return -1;
632    }
633    if (PyModule_AddStringConstant(m, "implementation",
634                                   "tiny_sha3") < 0) {
635        return -1;
636    }
637
638    return 0;
639}
640
641static PyModuleDef_Slot _sha3_slots[] = {
642    {Py_mod_exec, _sha3_exec},
643    {0, NULL}
644};
645
646/* Initialize this module. */
647static struct PyModuleDef _sha3module = {
648    PyModuleDef_HEAD_INIT,
649    .m_name = "_sha3",
650    .m_size = sizeof(SHA3State),
651    .m_slots = _sha3_slots,
652    .m_traverse = _sha3_traverse,
653    .m_clear = _sha3_clear,
654    .m_free = _sha3_free,
655};
656
657
658PyMODINIT_FUNC
659PyInit__sha3(void)
660{
661    return PyModuleDef_Init(&_sha3module);
662}
663