Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit e92ef13

Browse files
tirantiran
committed
Issue #18582: Add 'pbkdf2_hmac' to the hashlib module.
1 parent 3892419 commit e92ef13

6 files changed

Lines changed: 280 additions & 0 deletions

File tree

‎Doc/library/hashlib.rst‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,10 @@ digests. The modern term is secure hash.
3232
Some algorithms have known hash collision weaknesses, refer to the "See
3333
also" section at the end.
3434

35+
36+
Hash algorithms
37+
---------------
38+
3539
There is one constructor method named for each type of :dfn:`hash`. All return
3640
a hash object with the same simple interface. For example: use :func:`sha1` to
3741
create a SHA1 hash object. You can now feed this object with :term:`bytes-like
@@ -174,6 +178,43 @@ A hash object has the following methods:
174178
compute the digests of data sharing a common initial substring.
175179

176180

181+
Key Derivation Function
182+
-----------------------
183+
184+
Key derivation and key stretching algorithms are designed for secure password
185+
hashing. Naive algorithms such as ``sha1(password)`` are not resistant
186+
against brute-force attacks. A good password hashing function must be tunable,
187+
slow and include a salt.
188+
189+
190+
.. function:: pbkdf2_hmac(name, password, salt, rounds, dklen=None)
191+
192+
The function provides PKCS#5 password-based key derivation function 2. It
193+
uses HMAC as pseudorandom function.
194+
195+
The string *name* is the desired name of the hash digest algorithm for
196+
HMAC, e.g. 'sha1' or 'sha256'. *password* and *salt* are interpreted as
197+
buffers of bytes. Applications and libraries should limit *password* to
198+
a sensible value (e.g. 1024). *salt* should be about 16 or more bytes from
199+
a proper source, e.g. :func:`os.urandom`.
200+
201+
The number of *rounds* should be chosen based on the hash algorithm and
202+
computing power. As of 2013 a value of at least 100,000 rounds of SHA-256
203+
have been suggested.
204+
205+
*dklen* is the length of the derived key. If *dklen* is ``None`` then the
206+
digest size of the hash algorithm *name* is used, e.g. 64 for SHA-512.
207+
208+
>>> import hashlib, binascii
209+
>>> dk = hashlib.pbkdf2_hmac('sha256', b'password', b'salt', 100000)
210+
>>> binascii.hexlify(dk)
211+
b'0394a2ede332c9a13eb82e9b24631604c31df978b4e2f0fbd2c549944f9d79a5'
212+
213+
.. versionadded:: 3.4
214+
215+
.. note:: *pbkdf2_hmac* is only available with OpenSSL 1.0 and newer.
216+
217+
177218
.. seealso::
178219

179220
Module :mod:`hmac`
@@ -189,3 +230,5 @@ A hash object has the following methods:
189230
Wikipedia article with information on which algorithms have known issues and
190231
what that means regarding their use.
191232

233+
http://www.ietf.org/rfc/rfc2898.txt
234+
PKCS #5: Password-Based Cryptography Specification Version 2.0

‎Doc/whatsnew/3.4.rst‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -261,6 +261,14 @@ functools
261261
New :func:`functools.singledispatch` decorator: see the :pep:`443`.
262262

263263

264+
hashlib
265+
-------
266+
267+
New :func:`hashlib.pbkdf2_hmac` function.
268+
269+
(Contributed by Christian Heimes in :issue:`18582`)
270+
271+
264272
inspect
265273
-------
266274

‎Lib/hashlib.py‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -147,6 +147,14 @@ def __hash_new(name, data=b''):
147147
new = __py_new
148148
__get_hash = __get_builtin_constructor
149149

150+
# PBKDF2 requires OpenSSL 1.0+ with HMAC and SHA
151+
try:
152+
from _hashlib import pbkdf2_hmac
153+
except ImportError:
154+
pass
155+
else:
156+
__all__ += ('pbkdf2_hmac',)
157+
150158
for __func_name in __always_supported:
151159
# try them all, some may not work due to the OpenSSL
152160
# version not supporting that algorithm.

‎Lib/test/test_hashlib.py‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -545,6 +545,88 @@ def hash_in_chunks(chunk_size, event):
545545

546546
self.assertEqual(expected_hash, hasher.hexdigest())
547547

548+
pbkdf2_test_vectors = [
549+
(b'password', b'salt', 1, None),
550+
(b'password', b'salt', 2, None),
551+
(b'password', b'salt', 4096, None),
552+
# too slow, it takes over a minute on a fast CPU.
553+
#(b'password', b'salt', 16777216, None),
554+
(b'passwordPASSWORDpassword', b'saltSALTsaltSALTsaltSALTsaltSALTsalt',
555+
4096, -1),
556+
(b'pass\0word', b'sa\0lt', 4096, 16),
557+
]
558+
559+
pbkdf2_results = {
560+
"sha1": [
561+
# offical test vectors from RFC 6070
562+
(bytes.fromhex('0c60c80f961f0e71f3a9b524af6012062fe037a6'), None),
563+
(bytes.fromhex('ea6c014dc72d6f8ccd1ed92ace1d41f0d8de8957'), None),
564+
(bytes.fromhex('4b007901b765489abead49d926f721d065a429c1'), None),
565+
#(bytes.fromhex('eefe3d61cd4da4e4e9945b3d6ba2158c2634e984'), None),
566+
(bytes.fromhex('3d2eec4fe41c849b80c8d83662c0e44a8b291a964c'
567+
'f2f07038'), 25),
568+
(bytes.fromhex('56fa6aa75548099dcc37d7f03425e0c3'), None),],
569+
"sha256": [
570+
(bytes.fromhex('120fb6cffcf8b32c43e7225256c4f837'
571+
'a86548c92ccc35480805987cb70be17b'), None),
572+
(bytes.fromhex('ae4d0c95af6b46d32d0adff928f06dd0'
573+
'2a303f8ef3c251dfd6e2d85a95474c43'), None),
574+
(bytes.fromhex('c5e478d59288c841aa530db6845c4c8d'
575+
'962893a001ce4e11a4963873aa98134a'), None),
576+
#(bytes.fromhex('cf81c66fe8cfc04d1f31ecb65dab4089'
577+
# 'f7f179e89b3b0bcb17ad10e3ac6eba46'), None),
578+
(bytes.fromhex('348c89dbcbd32b2f32d814b8116e84cf2b17'
579+
'347ebc1800181c4e2a1fb8dd53e1c635518c7dac47e9'), 40),
580+
(bytes.fromhex('89b69d0516f829893c696226650a8687'), None),],
581+
"sha512": [
582+
(bytes.fromhex('867f70cf1ade02cff3752599a3a53dc4af34c7a669815ae5'
583+
'd513554e1c8cf252c02d470a285a0501bad999bfe943c08f'
584+
'050235d7d68b1da55e63f73b60a57fce'), None),
585+
(bytes.fromhex('e1d9c16aa681708a45f5c7c4e215ceb66e011a2e9f004071'
586+
'3f18aefdb866d53cf76cab2868a39b9f7840edce4fef5a82'
587+
'be67335c77a6068e04112754f27ccf4e'), None),
588+
(bytes.fromhex('d197b1b33db0143e018b12f3d1d1479e6cdebdcc97c5c0f8'
589+
'7f6902e072f457b5143f30602641b3d55cd335988cb36b84'
590+
'376060ecd532e039b742a239434af2d5'), None),
591+
(bytes.fromhex('8c0511f4c6e597c6ac6315d8f0362e225f3c501495ba23b8'
592+
'68c005174dc4ee71115b59f9e60cd9532fa33e0f75aefe30'
593+
'225c583a186cd82bd4daea9724a3d3b8'), 64),
594+
(bytes.fromhex('9d9e9c4cd21fe4be24d5b8244c759665'), None),],
595+
}
596+
597+
@unittest.skipUnless(hasattr(hashlib, 'pbkdf2_hmac'),
598+
'pbkdf2_hmac required for this test.')
599+
def test_pbkdf2_hmac(self):
600+
pbkdf2 = hashlib.pbkdf2_hmac
601+
602+
for digest_name, results in self.pbkdf2_results.items():
603+
for i, vector in enumerate(self.pbkdf2_test_vectors):
604+
password, salt, rounds, dklen = vector
605+
expected, overwrite_dklen = results[i]
606+
if overwrite_dklen:
607+
dklen = overwrite_dklen
608+
out = pbkdf2(digest_name, password, salt, rounds, dklen)
609+
self.assertEqual(out, expected,
610+
(digest_name, password, salt, rounds, dklen))
611+
out = pbkdf2(digest_name, memoryview(password),
612+
memoryview(salt), rounds, dklen)
613+
out = pbkdf2(digest_name, bytearray(password),
614+
bytearray(salt), rounds, dklen)
615+
self.assertEqual(out, expected)
616+
if dklen is None:
617+
out = pbkdf2(digest_name, password, salt, rounds)
618+
self.assertEqual(out, expected,
619+
(digest_name, password, salt, rounds))
620+
621+
self.assertRaises(TypeError, pbkdf2, b'sha1', b'pass', b'salt', 1)
622+
self.assertRaises(TypeError, pbkdf2, 'sha1', 'pass', 'salt', 1)
623+
self.assertRaises(ValueError, pbkdf2, 'sha1', b'pass', b'salt', 0)
624+
self.assertRaises(ValueError, pbkdf2, 'sha1', b'pass', b'salt', -1)
625+
self.assertRaises(ValueError, pbkdf2, 'sha1', b'pass', b'salt', 1, 0)
626+
self.assertRaises(ValueError, pbkdf2, 'sha1', b'pass', b'salt', 1, -1)
627+
with self.assertRaisesRegex(ValueError, 'unsupported hash type'):
628+
pbkdf2('unknown', b'pass', b'salt', 1)
629+
548630

549631
if __name__ == "__main__":
550632
unittest.main()

‎Misc/NEWS‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,9 @@ Core and Builtins
4242
Library
4343
-------
4444

45+
- Issue #18582: Add 'pbkdf2_hmac' to the hashlib module. It implements PKCS#5
46+
password-based key derivation functions with HMAC as pseudorandom function.
47+
4548
- Issue #19131: The aifc module now correctly reads and writes sampwidth of
4649
compressed streams.
4750

‎Modules/_hashopenssl.c‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@
2222
#include <openssl/evp.h>
2323
/* We use the object interface to discover what hashes OpenSSL supports. */
2424
#include <openssl/objects.h>
25+
#include "openssl/err.h"
2526

2627
#define MUNCH_SIZE INT_MAX
2728

@@ -61,6 +62,34 @@ DEFINE_CONSTS_FOR_NEW(sha384)
6162
DEFINE_CONSTS_FOR_NEW(sha512)
6263
#endif
6364

65+
static PyObject *
66+
_setException(PyObject *exc)
67+
{
68+
unsigned long errcode;
69+
const char *lib, *func, *reason;
70+
71+
errcode = ERR_peek_last_error();
72+
if (!errcode) {
73+
PyErr_SetString(exc, "unknown reasons");
74+
return NULL;
75+
}
76+
ERR_clear_error();
77+
78+
lib = ERR_lib_error_string(errcode);
79+
func = ERR_func_error_string(errcode);
80+
reason = ERR_reason_error_string(errcode);
81+
82+
if (lib && func) {
83+
PyErr_Format(exc, "[%s: %s] %s", lib, func, reason);
84+
}
85+
else if (lib) {
86+
PyErr_Format(exc, "[%s] %s", lib, reason);
87+
}
88+
else {
89+
PyErr_SetString(exc, reason);
90+
}
91+
return NULL;
92+
}
6493

6594
static EVPobject *
6695
newEVPobject(PyObject *name)
@@ -466,6 +495,109 @@ EVP_new(PyObject *self, PyObject *args, PyObject *kwdict)
466495
return ret_obj;
467496
}
468497

498+
#if (OPENSSL_VERSION_NUMBER >= 0x10000000 && !defined(OPENSSL_NO_HMAC) \
499+
&& !defined(OPENSSL_NO_SHA))
500+
#define PY_PBKDF2_HMAC 1
501+
502+
PyDoc_STRVAR(pbkdf2_hmac__doc__,
503+
"pbkdf2_hmac(hash_name, password, salt, iterations, dklen=None) -> key\n\
504+
\n\
505+
Password based key derivation function 2 (PKCS #5 v2.0) with HMAC as\n\
506+
pseudorandom function.");
507+
508+
static PyObject *
509+
pbkdf2_hmac(PyObject *self, PyObject *args, PyObject *kwdict)
510+
{
511+
static char *kwlist[] = {"hash_name", "password", "salt", "iterations",
512+
"dklen", NULL};
513+
PyObject *key_obj = NULL, *dklen_obj = Py_None;
514+
char *name, *key;
515+
Py_buffer password, salt;
516+
long iterations, dklen;
517+
int retval;
518+
const EVP_MD *digest;
519+
520+
if (!PyArg_ParseTupleAndKeywords(args, kwdict, "sy*y*l|O:pbkdf2_hmac",
521+
kwlist, &name, &password, &salt,
522+
&iterations, &dklen_obj)) {
523+
return NULL;
524+
}
525+
526+
digest = EVP_get_digestbyname(name);
527+
if (digest == NULL) {
528+
PyErr_SetString(PyExc_ValueError, "unsupported hash type");
529+
goto end;
530+
}
531+
532+
if (password.len > INT_MAX) {
533+
PyErr_SetString(PyExc_OverflowError,
534+
"password is too long.");
535+
goto end;
536+
}
537+
538+
if (salt.len > INT_MAX) {
539+
PyErr_SetString(PyExc_OverflowError,
540+
"salt is too long.");
541+
goto end;
542+
}
543+
544+
if (iterations < 1) {
545+
PyErr_SetString(PyExc_ValueError,
546+
"iteration value must be greater than 0.");
547+
goto end;
548+
}
549+
if (iterations > INT_MAX) {
550+
PyErr_SetString(PyExc_OverflowError,
551+
"iteration value is too great.");
552+
goto end;
553+
}
554+
555+
if (dklen_obj == Py_None) {
556+
dklen = EVP_MD_size(digest);
557+
} else {
558+
dklen = PyLong_AsLong(dklen_obj);
559+
if ((dklen == -1) && PyErr_Occurred()) {
560+
goto end;
561+
}
562+
}
563+
if (dklen < 1) {
564+
PyErr_SetString(PyExc_ValueError,
565+
"key length must be greater than 0.");
566+
goto end;
567+
}
568+
if (dklen > INT_MAX) {
569+
/* INT_MAX is always smaller than dkLen max (2^32 - 1) * hLen */
570+
PyErr_SetString(PyExc_OverflowError,
571+
"key length is too great.");
572+
goto end;
573+
}
574+
575+
key_obj = PyBytes_FromStringAndSize(NULL, dklen);
576+
if (key_obj == NULL) {
577+
goto end;
578+
}
579+
key = PyBytes_AS_STRING(key_obj);
580+
581+
Py_BEGIN_ALLOW_THREADS
582+
retval = PKCS5_PBKDF2_HMAC((char*)password.buf, password.len,
583+
(unsigned char *)salt.buf, salt.len,
584+
iterations, digest, dklen,
585+
(unsigned char *)key);
586+
Py_END_ALLOW_THREADS
587+
588+
if (!retval) {
589+
Py_CLEAR(key_obj);
590+
_setException(PyExc_ValueError);
591+
goto end;
592+
}
593+
594+
end:
595+
PyBuffer_Release(&password);
596+
PyBuffer_Release(&salt);
597+
return key_obj;
598+
}
599+
600+
#endif
469601

470602
/* State for our callback function so that it can accumulate a result. */
471603
typedef struct _internal_name_mapper_state {
@@ -588,6 +720,10 @@ GEN_CONSTRUCTOR(sha512)
588720

589721
static struct PyMethodDef EVP_functions[] = {
590722
{"new", (PyCFunction)EVP_new, METH_VARARGS|METH_KEYWORDS, EVP_new__doc__},
723+
#ifdef PY_PBKDF2_HMAC
724+
{"pbkdf2_hmac", (PyCFunction)pbkdf2_hmac, METH_VARARGS|METH_KEYWORDS,
725+
pbkdf2_hmac__doc__},
726+
#endif
591727
CONSTRUCTOR_METH_DEF(md5),
592728
CONSTRUCTOR_METH_DEF(sha1),
593729
#ifdef _OPENSSL_SUPPORTS_SHA2

0 commit comments

Comments
 (0)