1.. hazmat:: 2 3Key derivation functions 4======================== 5 6.. module:: cryptography.hazmat.primitives.kdf 7 8Key derivation functions derive bytes suitable for cryptographic operations 9from passwords or other data sources using a pseudo-random function (PRF). 10Different KDFs are suitable for different tasks such as: 11 12* Cryptographic key derivation 13 14 Deriving a key suitable for use as input to an encryption algorithm. 15 Typically this means taking a password and running it through an algorithm 16 such as :class:`~cryptography.hazmat.primitives.kdf.pbkdf2.PBKDF2HMAC` or 17 :class:`~cryptography.hazmat.primitives.kdf.hkdf.HKDF`. 18 This process is typically known as `key stretching`_. 19 20* Password storage 21 22 When storing passwords you want to use an algorithm that is computationally 23 intensive. Legitimate users will only need to compute it once (for example, 24 taking the user's password, running it through the KDF, then comparing it 25 to the stored value), while attackers will need to do it billions of times. 26 Ideal password storage KDFs will be demanding on both computational and 27 memory resources. 28 29.. currentmodule:: cryptography.hazmat.primitives.kdf.pbkdf2 30 31.. class:: PBKDF2HMAC(algorithm, length, salt, iterations, backend) 32 33 .. versionadded:: 0.2 34 35 `PBKDF2`_ (Password Based Key Derivation Function 2) is typically used for 36 deriving a cryptographic key from a password. It may also be used for 37 key storage, but an alternate key storage KDF such as 38 :class:`~cryptography.hazmat.primitives.kdf.scrypt.Scrypt` is generally 39 considered a better solution. 40 41 This class conforms to the 42 :class:`~cryptography.hazmat.primitives.kdf.KeyDerivationFunction` 43 interface. 44 45 .. doctest:: 46 47 >>> import os 48 >>> from cryptography.hazmat.primitives import hashes 49 >>> from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC 50 >>> from cryptography.hazmat.backends import default_backend 51 >>> backend = default_backend() 52 >>> # Salts should be randomly generated 53 >>> salt = os.urandom(16) 54 >>> # derive 55 >>> kdf = PBKDF2HMAC( 56 ... algorithm=hashes.SHA256(), 57 ... length=32, 58 ... salt=salt, 59 ... iterations=100000, 60 ... backend=backend 61 ... ) 62 >>> key = kdf.derive(b"my great password") 63 >>> # verify 64 >>> kdf = PBKDF2HMAC( 65 ... algorithm=hashes.SHA256(), 66 ... length=32, 67 ... salt=salt, 68 ... iterations=100000, 69 ... backend=backend 70 ... ) 71 >>> kdf.verify(b"my great password", key) 72 73 :param algorithm: An instance of 74 :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`. 75 :param int length: The desired length of the derived key in bytes. Maximum 76 is (2\ :sup:`32` - 1) * ``algorithm.digest_size``. 77 :param bytes salt: A salt. Secure values [#nist]_ are 128-bits (16 bytes) 78 or longer and randomly generated. 79 :param int iterations: The number of iterations to perform of the hash 80 function. This can be used to control the length of time the operation 81 takes. Higher numbers help mitigate brute force attacks against derived 82 keys. See OWASP's `Password Storage Cheat Sheet`_ for more 83 detailed recommendations if you intend to use this for password storage. 84 :param backend: An instance of 85 :class:`~cryptography.hazmat.backends.interfaces.PBKDF2HMACBackend`. 86 87 :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if the 88 provided ``backend`` does not implement 89 :class:`~cryptography.hazmat.backends.interfaces.PBKDF2HMACBackend` 90 91 :raises TypeError: This exception is raised if ``salt`` is not ``bytes``. 92 93 .. method:: derive(key_material) 94 95 :param key_material: The input key material. For PBKDF2 this 96 should be a password. 97 :type key_material: :term:`bytes-like` 98 :return bytes: the derived key. 99 :raises cryptography.exceptions.AlreadyFinalized: This is raised when 100 :meth:`derive` or 101 :meth:`verify` is 102 called more than 103 once. 104 105 :raises TypeError: This exception is raised if ``key_material`` is not 106 ``bytes``. 107 108 This generates and returns a new key from the supplied password. 109 110 .. method:: verify(key_material, expected_key) 111 112 :param bytes key_material: The input key material. This is the same as 113 ``key_material`` in :meth:`derive`. 114 :param bytes expected_key: The expected result of deriving a new key, 115 this is the same as the return value of 116 :meth:`derive`. 117 :raises cryptography.exceptions.InvalidKey: This is raised when the 118 derived key does not match 119 the expected key. 120 :raises cryptography.exceptions.AlreadyFinalized: This is raised when 121 :meth:`derive` or 122 :meth:`verify` is 123 called more than 124 once. 125 126 This checks whether deriving a new key from the supplied 127 ``key_material`` generates the same key as the ``expected_key``, and 128 raises an exception if they do not match. This can be used for 129 checking whether the password a user provides matches the stored derived 130 key. 131 132 133.. currentmodule:: cryptography.hazmat.primitives.kdf.hkdf 134 135.. class:: HKDF(algorithm, length, salt, info, backend) 136 137 .. versionadded:: 0.2 138 139 `HKDF`_ (HMAC-based Extract-and-Expand Key Derivation Function) is suitable 140 for deriving keys of a fixed size used for other cryptographic operations. 141 142 .. warning:: 143 144 HKDF should not be used for password storage. 145 146 .. doctest:: 147 148 >>> import os 149 >>> from cryptography.hazmat.primitives import hashes 150 >>> from cryptography.hazmat.primitives.kdf.hkdf import HKDF 151 >>> from cryptography.hazmat.backends import default_backend 152 >>> backend = default_backend() 153 >>> salt = os.urandom(16) 154 >>> info = b"hkdf-example" 155 >>> hkdf = HKDF( 156 ... algorithm=hashes.SHA256(), 157 ... length=32, 158 ... salt=salt, 159 ... info=info, 160 ... backend=backend 161 ... ) 162 >>> key = hkdf.derive(b"input key") 163 >>> hkdf = HKDF( 164 ... algorithm=hashes.SHA256(), 165 ... length=32, 166 ... salt=salt, 167 ... info=info, 168 ... backend=backend 169 ... ) 170 >>> hkdf.verify(b"input key", key) 171 172 :param algorithm: An instance of 173 :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`. 174 175 :param int length: The desired length of the derived key in bytes. Maximum 176 is ``255 * (algorithm.digest_size // 8)``. 177 178 :param bytes salt: A salt. Randomizes the KDF's output. Optional, but 179 highly recommended. Ideally as many bits of entropy as the security 180 level of the hash: often that means cryptographically random and as 181 long as the hash output. Worse (shorter, less entropy) salt values can 182 still meaningfully contribute to security. May be reused. Does not have 183 to be secret, but may cause stronger security guarantees if secret; see 184 :rfc:`5869` and the `HKDF paper`_ for more details. If ``None`` is 185 explicitly passed a default salt of ``algorithm.digest_size // 8`` null 186 bytes will be used. 187 188 :param bytes info: Application specific context information. If ``None`` 189 is explicitly passed an empty byte string will be used. 190 191 :param backend: An instance of 192 :class:`~cryptography.hazmat.backends.interfaces.HMACBackend`. 193 194 :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if the 195 provided ``backend`` does not implement 196 :class:`~cryptography.hazmat.backends.interfaces.HMACBackend` 197 198 :raises TypeError: This exception is raised if ``salt`` or ``info`` is not 199 ``bytes``. 200 201 .. method:: derive(key_material) 202 203 :param key_material: The input key material. 204 :type key_material: :term:`bytes-like` 205 :return bytes: The derived key. 206 :raises TypeError: This exception is raised if ``key_material`` is not 207 ``bytes``. 208 209 Derives a new key from the input key material by performing both the 210 extract and expand operations. 211 212 .. method:: verify(key_material, expected_key) 213 214 :param bytes key_material: The input key material. This is the same as 215 ``key_material`` in :meth:`derive`. 216 :param bytes expected_key: The expected result of deriving a new key, 217 this is the same as the return value of 218 :meth:`derive`. 219 :raises cryptography.exceptions.InvalidKey: This is raised when the 220 derived key does not match 221 the expected key. 222 :raises cryptography.exceptions.AlreadyFinalized: This is raised when 223 :meth:`derive` or 224 :meth:`verify` is 225 called more than 226 once. 227 228 This checks whether deriving a new key from the supplied 229 ``key_material`` generates the same key as the ``expected_key``, and 230 raises an exception if they do not match. 231 232 233.. class:: HKDFExpand(algorithm, length, info, backend) 234 235 .. versionadded:: 0.5 236 237 HKDF consists of two stages, extract and expand. This class exposes an 238 expand only version of HKDF that is suitable when the key material is 239 already cryptographically strong. 240 241 .. warning:: 242 243 HKDFExpand should only be used if the key material is 244 cryptographically strong. You should use 245 :class:`~cryptography.hazmat.primitives.kdf.hkdf.HKDF` if 246 you are unsure. 247 248 .. doctest:: 249 250 >>> import os 251 >>> from cryptography.hazmat.primitives import hashes 252 >>> from cryptography.hazmat.primitives.kdf.hkdf import HKDFExpand 253 >>> from cryptography.hazmat.backends import default_backend 254 >>> backend = default_backend() 255 >>> info = b"hkdf-example" 256 >>> key_material = os.urandom(16) 257 >>> hkdf = HKDFExpand( 258 ... algorithm=hashes.SHA256(), 259 ... length=32, 260 ... info=info, 261 ... backend=backend 262 ... ) 263 >>> key = hkdf.derive(key_material) 264 >>> hkdf = HKDFExpand( 265 ... algorithm=hashes.SHA256(), 266 ... length=32, 267 ... info=info, 268 ... backend=backend 269 ... ) 270 >>> hkdf.verify(key_material, key) 271 272 :param algorithm: An instance of 273 :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`. 274 275 :param int length: The desired length of the derived key in bytes. Maximum 276 is ``255 * (algorithm.digest_size // 8)``. 277 278 :param bytes info: Application specific context information. If ``None`` 279 is explicitly passed an empty byte string will be used. 280 281 :param backend: An instance of 282 :class:`~cryptography.hazmat.backends.interfaces.HMACBackend`. 283 284 :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if the 285 provided ``backend`` does not implement 286 :class:`~cryptography.hazmat.backends.interfaces.HMACBackend` 287 :raises TypeError: This exception is raised if ``info`` is not ``bytes``. 288 289 .. method:: derive(key_material) 290 291 :param bytes key_material: The input key material. 292 :return bytes: The derived key. 293 294 :raises TypeError: This exception is raised if ``key_material`` is not 295 ``bytes``. 296 297 Derives a new key from the input key material by performing both the 298 extract and expand operations. 299 300 .. method:: verify(key_material, expected_key) 301 302 :param bytes key_material: The input key material. This is the same as 303 ``key_material`` in :meth:`derive`. 304 :param bytes expected_key: The expected result of deriving a new key, 305 this is the same as the return value of 306 :meth:`derive`. 307 :raises cryptography.exceptions.InvalidKey: This is raised when the 308 derived key does not match 309 the expected key. 310 :raises cryptography.exceptions.AlreadyFinalized: This is raised when 311 :meth:`derive` or 312 :meth:`verify` is 313 called more than 314 once. 315 :raises TypeError: This is raised if the provided ``key_material`` is 316 a ``unicode`` object 317 318 This checks whether deriving a new key from the supplied 319 ``key_material`` generates the same key as the ``expected_key``, and 320 raises an exception if they do not match. 321 322.. currentmodule:: cryptography.hazmat.primitives.kdf.concatkdf 323 324.. class:: ConcatKDFHash(algorithm, length, otherinfo, backend) 325 326 .. versionadded:: 1.0 327 328 ConcatKDFHash (Concatenation Key Derivation Function) is defined by the 329 NIST Special Publication `NIST SP 800-56Ar2`_ document, to be used to 330 derive keys for use after a Key Exchange negotiation operation. 331 332 .. warning:: 333 334 ConcatKDFHash should not be used for password storage. 335 336 .. doctest:: 337 338 >>> import os 339 >>> from cryptography.hazmat.primitives import hashes 340 >>> from cryptography.hazmat.primitives.kdf.concatkdf import ConcatKDFHash 341 >>> from cryptography.hazmat.backends import default_backend 342 >>> backend = default_backend() 343 >>> otherinfo = b"concatkdf-example" 344 >>> ckdf = ConcatKDFHash( 345 ... algorithm=hashes.SHA256(), 346 ... length=32, 347 ... otherinfo=otherinfo, 348 ... backend=backend 349 ... ) 350 >>> key = ckdf.derive(b"input key") 351 >>> ckdf = ConcatKDFHash( 352 ... algorithm=hashes.SHA256(), 353 ... length=32, 354 ... otherinfo=otherinfo, 355 ... backend=backend 356 ... ) 357 >>> ckdf.verify(b"input key", key) 358 359 :param algorithm: An instance of 360 :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`. 361 362 :param int length: The desired length of the derived key in bytes. 363 Maximum is ``hashlen * (2^32 -1)``. 364 365 :param bytes otherinfo: Application specific context information. 366 If ``None`` is explicitly passed an empty byte string will be used. 367 368 :param backend: An instance of 369 :class:`~cryptography.hazmat.backends.interfaces.HashBackend`. 370 371 :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised 372 if the provided ``backend`` does not implement 373 :class:`~cryptography.hazmat.backends.interfaces.HashBackend` 374 375 :raises TypeError: This exception is raised if ``otherinfo`` is not 376 ``bytes``. 377 378 .. method:: derive(key_material) 379 380 :param key_material: The input key material. 381 :type key_material: :term:`bytes-like` 382 :return bytes: The derived key. 383 :raises TypeError: This exception is raised if ``key_material`` is 384 not ``bytes``. 385 386 Derives a new key from the input key material. 387 388 .. method:: verify(key_material, expected_key) 389 390 :param bytes key_material: The input key material. This is the same as 391 ``key_material`` in :meth:`derive`. 392 :param bytes expected_key: The expected result of deriving a new key, 393 this is the same as the return value of 394 :meth:`derive`. 395 :raises cryptography.exceptions.InvalidKey: This is raised when the 396 derived key does not match 397 the expected key. 398 :raises cryptography.exceptions.AlreadyFinalized: This is raised when 399 :meth:`derive` or 400 :meth:`verify` is 401 called more than 402 once. 403 404 This checks whether deriving a new key from the supplied 405 ``key_material`` generates the same key as the ``expected_key``, and 406 raises an exception if they do not match. 407 408 409.. class:: ConcatKDFHMAC(algorithm, length, salt, otherinfo, backend) 410 411 .. versionadded:: 1.0 412 413 Similar to ConcatKFDHash but uses an HMAC function instead. 414 415 .. warning:: 416 417 ConcatKDFHMAC should not be used for password storage. 418 419 .. doctest:: 420 421 >>> import os 422 >>> from cryptography.hazmat.primitives import hashes 423 >>> from cryptography.hazmat.primitives.kdf.concatkdf import ConcatKDFHMAC 424 >>> from cryptography.hazmat.backends import default_backend 425 >>> backend = default_backend() 426 >>> salt = os.urandom(16) 427 >>> otherinfo = b"concatkdf-example" 428 >>> ckdf = ConcatKDFHMAC( 429 ... algorithm=hashes.SHA256(), 430 ... length=32, 431 ... salt=salt, 432 ... otherinfo=otherinfo, 433 ... backend=backend 434 ... ) 435 >>> key = ckdf.derive(b"input key") 436 >>> ckdf = ConcatKDFHMAC( 437 ... algorithm=hashes.SHA256(), 438 ... length=32, 439 ... salt=salt, 440 ... otherinfo=otherinfo, 441 ... backend=backend 442 ... ) 443 >>> ckdf.verify(b"input key", key) 444 445 :param algorithm: An instance of 446 :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`. 447 448 :param int length: The desired length of the derived key in bytes. Maximum 449 is ``hashlen * (2^32 -1)``. 450 451 :param bytes salt: A salt. Randomizes the KDF's output. Optional, but 452 highly recommended. Ideally as many bits of entropy as the security 453 level of the hash: often that means cryptographically random and as 454 long as the hash output. Does not have to be secret, but may cause 455 stronger security guarantees if secret; If ``None`` is explicitly 456 passed a default salt of ``algorithm.block_size`` null bytes will be 457 used. 458 459 :param bytes otherinfo: Application specific context information. 460 If ``None`` is explicitly passed an empty byte string will be used. 461 462 :param backend: An instance of 463 :class:`~cryptography.hazmat.backends.interfaces.HMACBackend`. 464 465 :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if the 466 provided ``backend`` does not implement 467 :class:`~cryptography.hazmat.backends.interfaces.HMACBackend` 468 469 :raises TypeError: This exception is raised if ``salt`` or ``otherinfo`` 470 is not ``bytes``. 471 472 .. method:: derive(key_material) 473 474 :param bytes key_material: The input key material. 475 :return bytes: The derived key. 476 :raises TypeError: This exception is raised if ``key_material`` is not 477 ``bytes``. 478 479 Derives a new key from the input key material. 480 481 .. method:: verify(key_material, expected_key) 482 483 :param bytes key_material: The input key material. This is the same as 484 ``key_material`` in :meth:`derive`. 485 :param bytes expected_key: The expected result of deriving a new key, 486 this is the same as the return value of 487 :meth:`derive`. 488 :raises cryptography.exceptions.InvalidKey: This is raised when the 489 derived key does not match 490 the expected key. 491 :raises cryptography.exceptions.AlreadyFinalized: This is raised when 492 :meth:`derive` or 493 :meth:`verify` is 494 called more than 495 once. 496 497 This checks whether deriving a new key from the supplied 498 ``key_material`` generates the same key as the ``expected_key``, and 499 raises an exception if they do not match. 500 501.. currentmodule:: cryptography.hazmat.primitives.kdf.x963kdf 502 503.. class:: X963KDF(algorithm, length, otherinfo, backend) 504 505 .. versionadded:: 1.1 506 507 X963KDF (ANSI X9.63 Key Derivation Function) is defined by ANSI 508 in the `ANSI X9.63:2001`_ document, to be used to derive keys for use 509 after a Key Exchange negotiation operation. 510 511 SECG in `SEC 1 v2.0`_ recommends that 512 :class:`~cryptography.hazmat.primitives.kdf.concatkdf.ConcatKDFHash` be 513 used for new projects. This KDF should only be used for backwards 514 compatibility with pre-existing protocols. 515 516 517 .. warning:: 518 519 X963KDF should not be used for password storage. 520 521 .. doctest:: 522 523 >>> import os 524 >>> from cryptography.hazmat.primitives import hashes 525 >>> from cryptography.hazmat.primitives.kdf.x963kdf import X963KDF 526 >>> from cryptography.hazmat.backends import default_backend 527 >>> backend = default_backend() 528 >>> sharedinfo = b"ANSI X9.63 Example" 529 >>> xkdf = X963KDF( 530 ... algorithm=hashes.SHA256(), 531 ... length=32, 532 ... sharedinfo=sharedinfo, 533 ... backend=backend 534 ... ) 535 >>> key = xkdf.derive(b"input key") 536 >>> xkdf = X963KDF( 537 ... algorithm=hashes.SHA256(), 538 ... length=32, 539 ... sharedinfo=sharedinfo, 540 ... backend=backend 541 ... ) 542 >>> xkdf.verify(b"input key", key) 543 544 :param algorithm: An instance of 545 :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`. 546 547 :param int length: The desired length of the derived key in bytes. 548 Maximum is ``hashlen * (2^32 -1)``. 549 550 :param bytes sharedinfo: Application specific context information. 551 If ``None`` is explicitly passed an empty byte string will be used. 552 553 :param backend: A cryptography backend 554 :class:`~cryptography.hazmat.backends.interfaces.HashBackend` 555 instance. 556 557 :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised 558 if the provided ``backend`` does not implement 559 :class:`~cryptography.hazmat.backends.interfaces.HashBackend` 560 561 :raises TypeError: This exception is raised if ``sharedinfo`` is not 562 ``bytes``. 563 564 .. method:: derive(key_material) 565 566 :param key_material: The input key material. 567 :type key_material: :term:`bytes-like` 568 :return bytes: The derived key. 569 :raises TypeError: This exception is raised if ``key_material`` is 570 not ``bytes``. 571 572 Derives a new key from the input key material. 573 574 .. method:: verify(key_material, expected_key) 575 576 :param bytes key_material: The input key material. This is the same as 577 ``key_material`` in :meth:`derive`. 578 :param bytes expected_key: The expected result of deriving a new key, 579 this is the same as the return value of 580 :meth:`derive`. 581 :raises cryptography.exceptions.InvalidKey: This is raised when the 582 derived key does not match 583 the expected key. 584 :raises cryptography.exceptions.AlreadyFinalized: This is raised when 585 :meth:`derive` or 586 :meth:`verify` is 587 called more than 588 once. 589 590 This checks whether deriving a new key from the supplied 591 ``key_material`` generates the same key as the ``expected_key``, and 592 raises an exception if they do not match. 593 594 595.. currentmodule:: cryptography.hazmat.primitives.kdf.kbkdf 596 597.. class:: KBKDFHMAC(algorithm, mode, length, rlen, llen, location,\ 598 label, context, fixed, backend) 599 600 .. versionadded:: 1.4 601 602 KBKDF (Key Based Key Derivation Function) is defined by the 603 `NIST SP 800-108`_ document, to be used to derive additional 604 keys from a key that has been established through an automated 605 key-establishment scheme. 606 607 .. warning:: 608 609 KBKDFHMAC should not be used for password storage. 610 611 .. doctest:: 612 613 >>> import os 614 >>> from cryptography.hazmat.primitives import hashes 615 >>> from cryptography.hazmat.primitives.kdf.kbkdf import ( 616 ... CounterLocation, KBKDFHMAC, Mode 617 ... ) 618 >>> from cryptography.hazmat.backends import default_backend 619 >>> backend = default_backend() 620 >>> label = b"KBKDF HMAC Label" 621 >>> context = b"KBKDF HMAC Context" 622 >>> kdf = KBKDFHMAC( 623 ... algorithm=hashes.SHA256(), 624 ... mode=Mode.CounterMode, 625 ... length=32, 626 ... rlen=4, 627 ... llen=4, 628 ... location=CounterLocation.BeforeFixed, 629 ... label=label, 630 ... context=context, 631 ... fixed=None, 632 ... backend=backend 633 ... ) 634 >>> key = kdf.derive(b"input key") 635 >>> kdf = KBKDFHMAC( 636 ... algorithm=hashes.SHA256(), 637 ... mode=Mode.CounterMode, 638 ... length=32, 639 ... rlen=4, 640 ... llen=4, 641 ... location=CounterLocation.BeforeFixed, 642 ... label=label, 643 ... context=context, 644 ... fixed=None, 645 ... backend=backend 646 ... ) 647 >>> kdf.verify(b"input key", key) 648 649 :param algorithm: An instance of 650 :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`. 651 652 :param mode: The desired mode of the PRF. A value from the 653 :class:`~cryptography.hazmat.primitives.kdf.kbkdf.Mode` enum. 654 655 :param int length: The desired length of the derived key in bytes. 656 657 :param int rlen: An integer that indicates the length of the binary 658 representation of the counter in bytes. 659 660 :param int llen: An integer that indicates the binary 661 representation of the ``length`` in bytes. 662 663 :param location: The desired location of the counter. A value from the 664 :class:`~cryptography.hazmat.primitives.kdf.kbkdf.CounterLocation` enum. 665 666 :param bytes label: Application specific label information. If ``None`` 667 is explicitly passed an empty byte string will be used. 668 669 :param bytes context: Application specific context information. If ``None`` 670 is explicitly passed an empty byte string will be used. 671 672 :param bytes fixed: Instead of specifying ``label`` and ``context`` you 673 may supply your own fixed data. If ``fixed`` is specified, ``label`` 674 and ``context`` is ignored. 675 676 :param backend: A cryptography backend 677 :class:`~cryptography.hazmat.backends.interfaces.HashBackend` 678 instance. 679 680 :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised 681 if the provided ``backend`` does not implement 682 :class:`~cryptography.hazmat.backends.interfaces.HashBackend` 683 684 :raises TypeError: This exception is raised if ``label`` or ``context`` 685 is not ``bytes``. Also raised if ``rlen`` or ``llen`` is not ``int``. 686 687 :raises ValueError: This exception is raised if ``rlen`` or ``llen`` 688 is greater than 4 or less than 1. This exception is also raised if 689 you specify a ``label`` or ``context`` and ``fixed``. 690 691 .. method:: derive(key_material) 692 693 :param key_material: The input key material. 694 :type key_material: :term:`bytes-like` 695 :return bytes: The derived key. 696 :raises TypeError: This exception is raised if ``key_material`` is 697 not ``bytes``. 698 699 Derives a new key from the input key material. 700 701 .. method:: verify(key_material, expected_key) 702 703 :param bytes key_material: The input key material. This is the same as 704 ``key_material`` in :meth:`derive`. 705 :param bytes expected_key: The expected result of deriving a new key, 706 this is the same as the return value of 707 :meth:`derive`. 708 :raises cryptography.exceptions.InvalidKey: This is raised when the 709 derived key does not match 710 the expected key. 711 :raises cryptography.exceptions.AlreadyFinalized: This is raised when 712 :meth:`derive` or 713 :meth:`verify` is 714 called more than 715 once. 716 717 This checks whether deriving a new key from the supplied 718 ``key_material`` generates the same key as the ``expected_key``, and 719 raises an exception if they do not match. 720 721.. class:: Mode 722 723 An enumeration for the key based key derivative modes. 724 725 .. attribute:: CounterMode 726 727 The output of the PRF is computed with a counter 728 as the iteration variable. 729 730.. class:: CounterLocation 731 732 An enumeration for the key based key derivative counter location. 733 734 .. attribute:: BeforeFixed 735 736 The counter iteration variable will be concatenated before 737 the fixed input data. 738 739 .. attribute:: AfterFixed 740 741 The counter iteration variable will be concatenated after 742 the fixed input data. 743 744.. currentmodule:: cryptography.hazmat.primitives.kdf.scrypt 745 746.. class:: Scrypt(salt, length, n, r, p, backend) 747 748 .. versionadded:: 1.6 749 750 Scrypt is a KDF designed for password storage by Colin Percival to be 751 resistant against hardware-assisted attackers by having a tunable memory 752 cost. It is described in :rfc:`7914`. 753 754 This class conforms to the 755 :class:`~cryptography.hazmat.primitives.kdf.KeyDerivationFunction` 756 interface. 757 758 .. doctest:: 759 760 >>> import os 761 >>> from cryptography.hazmat.primitives.kdf.scrypt import Scrypt 762 >>> from cryptography.hazmat.backends import default_backend 763 >>> backend = default_backend() 764 >>> salt = os.urandom(16) 765 >>> # derive 766 >>> kdf = Scrypt( 767 ... salt=salt, 768 ... length=32, 769 ... n=2**14, 770 ... r=8, 771 ... p=1, 772 ... backend=backend 773 ... ) 774 >>> key = kdf.derive(b"my great password") 775 >>> # verify 776 >>> kdf = Scrypt( 777 ... salt=salt, 778 ... length=32, 779 ... n=2**14, 780 ... r=8, 781 ... p=1, 782 ... backend=backend 783 ... ) 784 >>> kdf.verify(b"my great password", key) 785 786 :param bytes salt: A salt. 787 :param int length: The desired length of the derived key in bytes. 788 :param int n: CPU/Memory cost parameter. It must be larger than 1 and be a 789 power of 2. 790 :param int r: Block size parameter. 791 :param int p: Parallelization parameter. 792 793 The computational and memory cost of Scrypt can be adjusted by manipulating 794 the 3 parameters: ``n``, ``r``, and ``p``. In general, the memory cost of 795 Scrypt is affected by the values of both ``n`` and ``r``, while ``n`` also 796 determines the number of iterations performed. ``p`` increases the 797 computational cost without affecting memory usage. A more in-depth 798 explanation of the 3 parameters can be found `here`_. 799 800 :rfc:`7914` `recommends`_ values of ``r=8`` and ``p=1`` while scaling ``n`` 801 to a number appropriate for your system. `The scrypt paper`_ suggests a 802 minimum value of ``n=2**14`` for interactive logins (t < 100ms), or 803 ``n=2**20`` for more sensitive files (t < 5s). 804 805 :param backend: An instance of 806 :class:`~cryptography.hazmat.backends.interfaces.ScryptBackend`. 807 808 :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if the 809 provided ``backend`` does not implement 810 :class:`~cryptography.hazmat.backends.interfaces.ScryptBackend` 811 812 :raises TypeError: This exception is raised if ``salt`` is not ``bytes``. 813 :raises ValueError: This exception is raised if ``n`` is less than 2, if 814 ``n`` is not a power of 2, if ``r`` is less than 1 or if ``p`` is less 815 than 1. 816 817 .. method:: derive(key_material) 818 819 :param key_material: The input key material. 820 :type key_material: :term:`bytes-like` 821 :return bytes: the derived key. 822 :raises TypeError: This exception is raised if ``key_material`` is not 823 ``bytes``. 824 :raises cryptography.exceptions.AlreadyFinalized: This is raised when 825 :meth:`derive` or 826 :meth:`verify` is 827 called more than 828 once. 829 830 This generates and returns a new key from the supplied password. 831 832 .. method:: verify(key_material, expected_key) 833 834 :param bytes key_material: The input key material. This is the same as 835 ``key_material`` in :meth:`derive`. 836 :param bytes expected_key: The expected result of deriving a new key, 837 this is the same as the return value of 838 :meth:`derive`. 839 :raises cryptography.exceptions.InvalidKey: This is raised when the 840 derived key does not match 841 the expected key. 842 :raises cryptography.exceptions.AlreadyFinalized: This is raised when 843 :meth:`derive` or 844 :meth:`verify` is 845 called more than 846 once. 847 848 This checks whether deriving a new key from the supplied 849 ``key_material`` generates the same key as the ``expected_key``, and 850 raises an exception if they do not match. This can be used for 851 checking whether the password a user provides matches the stored derived 852 key. 853 854Interface 855~~~~~~~~~ 856 857.. currentmodule:: cryptography.hazmat.primitives.kdf 858 859.. class:: KeyDerivationFunction 860 861 .. versionadded:: 0.2 862 863 .. method:: derive(key_material) 864 865 :param bytes key_material: The input key material. Depending on what 866 key derivation function you are using this 867 could be either random bytes, or a user 868 supplied password. 869 :return: The new key. 870 :raises cryptography.exceptions.AlreadyFinalized: This is raised when 871 :meth:`derive` or 872 :meth:`verify` is 873 called more than 874 once. 875 876 This generates and returns a new key from the supplied key material. 877 878 .. method:: verify(key_material, expected_key) 879 880 :param bytes key_material: The input key material. This is the same as 881 ``key_material`` in :meth:`derive`. 882 :param bytes expected_key: The expected result of deriving a new key, 883 this is the same as the return value of 884 :meth:`derive`. 885 :raises cryptography.exceptions.InvalidKey: This is raised when the 886 derived key does not match 887 the expected key. 888 :raises cryptography.exceptions.AlreadyFinalized: This is raised when 889 :meth:`derive` or 890 :meth:`verify` is 891 called more than 892 once. 893 894 This checks whether deriving a new key from the supplied 895 ``key_material`` generates the same key as the ``expected_key``, and 896 raises an exception if they do not match. This can be used for 897 something like checking whether a user's password attempt matches the 898 stored derived key. 899 900 901.. [#nist] See `NIST SP 800-132`_. 902 903.. _`NIST SP 800-132`: https://csrc.nist.gov/publications/detail/sp/800-132/final 904.. _`NIST SP 800-108`: https://csrc.nist.gov/publications/detail/sp/800-108/final 905.. _`NIST SP 800-56Ar2`: https://csrc.nist.gov/publications/detail/sp/800-56a/rev-2/final 906.. _`ANSI X9.63:2001`: https://webstore.ansi.org 907.. _`SEC 1 v2.0`: http://www.secg.org/sec1-v2.pdf 908.. _`Password Storage Cheat Sheet`: https://www.owasp.org/index.php/Password_Storage_Cheat_Sheet 909.. _`PBKDF2`: https://en.wikipedia.org/wiki/PBKDF2 910.. _`key stretching`: https://en.wikipedia.org/wiki/Key_stretching 911.. _`HKDF`: https://en.wikipedia.org/wiki/HKDF 912.. _`HKDF paper`: https://eprint.iacr.org/2010/264 913.. _`here`: https://stackoverflow.com/a/30308723/1170681 914.. _`recommends`: https://tools.ietf.org/html/rfc7914#section-2 915.. _`The scrypt paper`: https://www.tarsnap.com/scrypt/scrypt.pdf 916