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