1.. hazmat:: /fernet 2 3 4Symmetric encryption 5==================== 6 7.. module:: cryptography.hazmat.primitives.ciphers 8 9Symmetric encryption is a way to `encrypt`_ or hide the contents of material 10where the sender and receiver both use the same secret key. Note that symmetric 11encryption is **not** sufficient for most applications because it only 12provides secrecy but not authenticity. That means an attacker can't see the 13message but an attacker can create bogus messages and force the application to 14decrypt them. In many contexts, a lack of authentication on encrypted messages 15can result in a loss of secrecy as well. 16 17For this reason it is **strongly** recommended to combine encryption with a 18message authentication code, such as :doc:`HMAC </hazmat/primitives/mac/hmac>`, 19in an "encrypt-then-MAC" formulation as `described by Colin Percival`_. 20``cryptography`` includes a recipe named :doc:`/fernet` that does this for you. 21**To minimize the risk of security issues you should evaluate Fernet to see if 22it fits your needs before implementing anything using this module.** 23 24.. class:: Cipher(algorithm, mode, backend=None) 25 26 Cipher objects combine an algorithm such as 27 :class:`~cryptography.hazmat.primitives.ciphers.algorithms.AES` with a 28 mode like 29 :class:`~cryptography.hazmat.primitives.ciphers.modes.CBC` or 30 :class:`~cryptography.hazmat.primitives.ciphers.modes.CTR`. A simple 31 example of encrypting and then decrypting content with AES is: 32 33 .. doctest:: 34 35 >>> import os 36 >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes 37 >>> key = os.urandom(32) 38 >>> iv = os.urandom(16) 39 >>> cipher = Cipher(algorithms.AES(key), modes.CBC(iv)) 40 >>> encryptor = cipher.encryptor() 41 >>> ct = encryptor.update(b"a secret message") + encryptor.finalize() 42 >>> decryptor = cipher.decryptor() 43 >>> decryptor.update(ct) + decryptor.finalize() 44 b'a secret message' 45 46 :param algorithm: A 47 :class:`~cryptography.hazmat.primitives.ciphers.CipherAlgorithm` 48 instance such as those described 49 :ref:`below <symmetric-encryption-algorithms>`. 50 :param mode: A :class:`~cryptography.hazmat.primitives.ciphers.modes.Mode` 51 instance such as those described 52 :ref:`below <symmetric-encryption-modes>`. 53 :param backend: An optional 54 :class:`~cryptography.hazmat.backends.interfaces.CipherBackend` 55 instance. 56 57 :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if the 58 provided ``backend`` does not implement 59 :class:`~cryptography.hazmat.backends.interfaces.CipherBackend` 60 61 .. method:: encryptor() 62 63 :return: An encrypting 64 :class:`~cryptography.hazmat.primitives.ciphers.CipherContext` 65 instance. 66 67 If the backend doesn't support the requested combination of ``cipher`` 68 and ``mode`` an :class:`~cryptography.exceptions.UnsupportedAlgorithm` 69 exception will be raised. 70 71 .. method:: decryptor() 72 73 :return: A decrypting 74 :class:`~cryptography.hazmat.primitives.ciphers.CipherContext` 75 instance. 76 77 If the backend doesn't support the requested combination of ``cipher`` 78 and ``mode`` an :class:`~cryptography.exceptions.UnsupportedAlgorithm` 79 exception will be raised. 80 81.. _symmetric-encryption-algorithms: 82 83Algorithms 84~~~~~~~~~~ 85 86.. currentmodule:: cryptography.hazmat.primitives.ciphers.algorithms 87 88.. class:: AES(key) 89 90 AES (Advanced Encryption Standard) is a block cipher standardized by NIST. 91 AES is both fast, and cryptographically strong. It is a good default 92 choice for encryption. 93 94 :param key: The secret key. This must be kept secret. Either ``128``, 95 ``192``, or ``256`` :term:`bits` long. 96 :type key: :term:`bytes-like` 97 98.. class:: Camellia(key) 99 100 Camellia is a block cipher approved for use by `CRYPTREC`_ and ISO/IEC. 101 It is considered to have comparable security and performance to AES but 102 is not as widely studied or deployed. 103 104 :param key: The secret key. This must be kept secret. Either ``128``, 105 ``192``, or ``256`` :term:`bits` long. 106 :type key: :term:`bytes-like` 107 108.. class:: ChaCha20(key) 109 110 .. versionadded:: 2.1 111 112 .. note:: 113 114 In most cases users should use 115 :class:`~cryptography.hazmat.primitives.ciphers.aead.ChaCha20Poly1305` 116 instead of this class. `ChaCha20` alone does not provide integrity 117 so it must be combined with a MAC to be secure. 118 :class:`~cryptography.hazmat.primitives.ciphers.aead.ChaCha20Poly1305` 119 does this for you. 120 121 ChaCha20 is a stream cipher used in several IETF protocols. It is 122 standardized in :rfc:`7539`. 123 124 :param key: The secret key. This must be kept secret. ``256`` 125 :term:`bits` (32 bytes) in length. 126 :type key: :term:`bytes-like` 127 128 :param nonce: Should be unique, a :term:`nonce`. It is 129 critical to never reuse a ``nonce`` with a given key. Any reuse of a 130 nonce with the same key compromises the security of every message 131 encrypted with that key. The nonce does not need to be kept secret 132 and may be included with the ciphertext. This must be ``128`` 133 :term:`bits` in length. 134 :type nonce: :term:`bytes-like` 135 136 .. note:: 137 138 In :rfc:`7539` the nonce is defined as a 96-bit value that is later 139 concatenated with a block counter (encoded as a 32-bit 140 little-endian). If you have a separate nonce and block counter 141 you will need to concatenate it yourself before passing it. For 142 example, if you have an initial block counter of 2 and a 96-bit 143 nonce the concatenated nonce would be 144 ``struct.pack("<i", 2) + nonce``. 145 146 .. doctest:: 147 148 >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes 149 >>> nonce = os.urandom(16) 150 >>> algorithm = algorithms.ChaCha20(key, nonce) 151 >>> cipher = Cipher(algorithm, mode=None) 152 >>> encryptor = cipher.encryptor() 153 >>> ct = encryptor.update(b"a secret message") 154 >>> decryptor = cipher.decryptor() 155 >>> decryptor.update(ct) 156 b'a secret message' 157 158.. class:: TripleDES(key) 159 160 Triple DES (Data Encryption Standard), sometimes referred to as 3DES, is a 161 block cipher standardized by NIST. Triple DES has known crypto-analytic 162 flaws, however none of them currently enable a practical attack. 163 Nonetheless, Triple DES is not recommended for new applications because it 164 is incredibly slow; old applications should consider moving away from it. 165 166 :param key: The secret key. This must be kept secret. Either ``64``, 167 ``128``, or ``192`` :term:`bits` long. DES only uses ``56``, ``112``, 168 or ``168`` bits of the key as there is a parity byte in each component 169 of the key. Some writing refers to there being up to three separate 170 keys that are each ``56`` bits long, they can simply be concatenated 171 to produce the full key. 172 :type key: :term:`bytes-like` 173 174.. class:: CAST5(key) 175 176 .. versionadded:: 0.2 177 178 CAST5 (also known as CAST-128) is a block cipher approved for use in the 179 Canadian government by the `Communications Security Establishment`_. It is 180 a variable key length cipher and supports keys from 40-128 :term:`bits` in 181 length. 182 183 :param key: The secret key, This must be kept secret. 40 to 128 184 :term:`bits` in length in increments of 8 bits. 185 :type key: :term:`bytes-like` 186 187.. class:: SEED(key) 188 189 .. versionadded:: 0.4 190 191 SEED is a block cipher developed by the Korea Information Security Agency 192 (KISA). It is defined in :rfc:`4269` and is used broadly throughout South 193 Korean industry, but rarely found elsewhere. 194 195 :param key: The secret key. This must be kept secret. ``128`` 196 :term:`bits` in length. 197 :type key: :term:`bytes-like` 198 199Weak ciphers 200------------ 201 202.. warning:: 203 204 These ciphers are considered weak for a variety of reasons. New 205 applications should avoid their use and existing applications should 206 strongly consider migrating away. 207 208.. class:: Blowfish(key) 209 210 Blowfish is a block cipher developed by Bruce Schneier. It is known to be 211 susceptible to attacks when using weak keys. The author has recommended 212 that users of Blowfish move to newer algorithms such as :class:`AES`. 213 214 :param key: The secret key. This must be kept secret. 32 to 448 215 :term:`bits` in length in increments of 8 bits. 216 :type key: :term:`bytes-like` 217 218.. class:: ARC4(key) 219 220 ARC4 (Alleged RC4) is a stream cipher with serious weaknesses in its 221 initial stream output. Its use is strongly discouraged. ARC4 does not use 222 mode constructions. 223 224 :param key: The secret key. This must be kept secret. Either ``40``, 225 ``56``, ``64``, ``80``, ``128``, ``192``, or ``256`` :term:`bits` in 226 length. 227 :type key: :term:`bytes-like` 228 229 .. doctest:: 230 231 >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes 232 >>> algorithm = algorithms.ARC4(key) 233 >>> cipher = Cipher(algorithm, mode=None) 234 >>> encryptor = cipher.encryptor() 235 >>> ct = encryptor.update(b"a secret message") 236 >>> decryptor = cipher.decryptor() 237 >>> decryptor.update(ct) 238 b'a secret message' 239 240.. class:: IDEA(key) 241 242 IDEA (`International Data Encryption Algorithm`_) is a block cipher created 243 in 1991. It is an optional component of the `OpenPGP`_ standard. This cipher 244 is susceptible to attacks when using weak keys. It is recommended that you 245 do not use this cipher for new applications. 246 247 :param key: The secret key. This must be kept secret. ``128`` 248 :term:`bits` in length. 249 :type key: :term:`bytes-like` 250 251 252.. _symmetric-encryption-modes: 253 254Modes 255~~~~~ 256 257.. module:: cryptography.hazmat.primitives.ciphers.modes 258 259.. class:: CBC(initialization_vector) 260 261 CBC (Cipher Block Chaining) is a mode of operation for block ciphers. It is 262 considered cryptographically strong. 263 264 **Padding is required when using this mode.** 265 266 :param initialization_vector: Must be :doc:`random bytes 267 </random-numbers>`. They do not need to be kept secret and they can be 268 included in a transmitted message. Must be the same number of bytes as 269 the ``block_size`` of the cipher. Each time something is encrypted a 270 new ``initialization_vector`` should be generated. Do not reuse an 271 ``initialization_vector`` with a given ``key``, and particularly do not 272 use a constant ``initialization_vector``. 273 :type initialization_vector: :term:`bytes-like` 274 275 A good construction looks like: 276 277 .. doctest:: 278 279 >>> import os 280 >>> from cryptography.hazmat.primitives.ciphers.modes import CBC 281 >>> iv = os.urandom(16) 282 >>> mode = CBC(iv) 283 284 While the following is bad and will leak information: 285 286 .. doctest:: 287 288 >>> from cryptography.hazmat.primitives.ciphers.modes import CBC 289 >>> iv = b"a" * 16 290 >>> mode = CBC(iv) 291 292 293.. class:: CTR(nonce) 294 295 .. warning:: 296 297 Counter mode is not recommended for use with block ciphers that have a 298 block size of less than 128-:term:`bits`. 299 300 CTR (Counter) is a mode of operation for block ciphers. It is considered 301 cryptographically strong. It transforms a block cipher into a stream 302 cipher. 303 304 **This mode does not require padding.** 305 306 :param nonce: Should be unique, a :term:`nonce`. It is 307 critical to never reuse a ``nonce`` with a given key. Any reuse of a 308 nonce with the same key compromises the security of every message 309 encrypted with that key. Must be the same number of bytes as the 310 ``block_size`` of the cipher with a given key. The nonce does not need 311 to be kept secret and may be included with the ciphertext. 312 :type nonce: :term:`bytes-like` 313 314.. class:: OFB(initialization_vector) 315 316 OFB (Output Feedback) is a mode of operation for block ciphers. It 317 transforms a block cipher into a stream cipher. 318 319 **This mode does not require padding.** 320 321 :param initialization_vector: Must be :doc:`random bytes 322 </random-numbers>`. They do not need to be kept secret and they can be 323 included in a transmitted message. Must be the same number of bytes as 324 the ``block_size`` of the cipher. Do not reuse an 325 ``initialization_vector`` with a given ``key``. 326 :type initialization_vector: :term:`bytes-like` 327 328.. class:: CFB(initialization_vector) 329 330 CFB (Cipher Feedback) is a mode of operation for block ciphers. It 331 transforms a block cipher into a stream cipher. 332 333 **This mode does not require padding.** 334 335 :param initialization_vector: Must be :doc:`random bytes 336 </random-numbers>`. They do not need to be kept secret and they can be 337 included in a transmitted message. Must be the same number of bytes as 338 the ``block_size`` of the cipher. Do not reuse an 339 ``initialization_vector`` with a given ``key``. 340 :type initialization_vector: :term:`bytes-like` 341 342.. class:: CFB8(initialization_vector) 343 344 CFB (Cipher Feedback) is a mode of operation for block ciphers. It 345 transforms a block cipher into a stream cipher. The CFB8 variant uses an 346 8-bit shift register. 347 348 **This mode does not require padding.** 349 350 :param initialization_vector: Must be :doc:`random bytes 351 </random-numbers>`. They do not need to be kept secret and they can be 352 included in a transmitted message. Must be the same number of bytes as 353 the ``block_size`` of the cipher. Do not reuse an 354 ``initialization_vector`` with a given ``key``. 355 :type initialization_vector: :term:`bytes-like` 356 357.. class:: GCM(initialization_vector, tag=None, min_tag_length=16) 358 359 .. danger:: 360 361 If you are encrypting data that can fit into memory you should strongly 362 consider using 363 :class:`~cryptography.hazmat.primitives.ciphers.aead.AESGCM` instead 364 of this. 365 366 When using this mode you **must** not use the decrypted data until 367 the appropriate finalization method 368 (:meth:`~cryptography.hazmat.primitives.ciphers.CipherContext.finalize` 369 or 370 :meth:`~cryptography.hazmat.primitives.ciphers.AEADDecryptionContext.finalize_with_tag`) 371 has been called. GCM provides **no** guarantees of ciphertext integrity 372 until decryption is complete. 373 374 GCM (Galois Counter Mode) is a mode of operation for block ciphers. An 375 AEAD (authenticated encryption with additional data) mode is a type of 376 block cipher mode that simultaneously encrypts the message as well as 377 authenticating it. Additional unencrypted data may also be authenticated. 378 Additional means of verifying integrity such as 379 :doc:`HMAC </hazmat/primitives/mac/hmac>` are not necessary. 380 381 **This mode does not require padding.** 382 383 :param initialization_vector: Must be unique, a :term:`nonce`. 384 They do not need to be kept secret and they can be included in a 385 transmitted message. NIST `recommends a 96-bit IV length`_ for 386 performance critical situations but it can be up to 2\ :sup:`64` - 1 387 :term:`bits`. Do not reuse an ``initialization_vector`` with a given 388 ``key``. 389 :type initialization_vector: :term:`bytes-like` 390 391 .. note:: 392 393 Cryptography will generate a 128-bit tag when finalizing encryption. 394 You can shorten a tag by truncating it to the desired length but this 395 is **not recommended** as it makes it easier to forge messages, and 396 also potentially leaks the key (`NIST SP-800-38D`_ recommends 397 96-:term:`bits` or greater). Applications wishing to allow truncation 398 can pass the ``min_tag_length`` parameter. 399 400 .. versionchanged:: 0.5 401 402 The ``min_tag_length`` parameter was added in ``0.5``, previously 403 truncation down to ``4`` bytes was always allowed. 404 405 :param bytes tag: The tag bytes to verify during decryption. When 406 encrypting this must be ``None``. When decrypting, it may be ``None`` 407 if the tag is supplied on finalization using 408 :meth:`~cryptography.hazmat.primitives.ciphers.AEADDecryptionContext.finalize_with_tag`. 409 Otherwise, the tag is mandatory. 410 411 :param int min_tag_length: The minimum length ``tag`` must be. By default 412 this is ``16``, meaning tag truncation is not allowed. Allowing tag 413 truncation is strongly discouraged for most applications. 414 415 :raises ValueError: This is raised if ``len(tag) < min_tag_length`` or the 416 ``initialization_vector`` is too short. 417 418 An example of securely encrypting and decrypting data with ``AES`` in the 419 ``GCM`` mode looks like: 420 421 .. testcode:: 422 423 import os 424 425 from cryptography.hazmat.primitives.ciphers import ( 426 Cipher, algorithms, modes 427 ) 428 429 def encrypt(key, plaintext, associated_data): 430 # Generate a random 96-bit IV. 431 iv = os.urandom(12) 432 433 # Construct an AES-GCM Cipher object with the given key and a 434 # randomly generated IV. 435 encryptor = Cipher( 436 algorithms.AES(key), 437 modes.GCM(iv), 438 ).encryptor() 439 440 # associated_data will be authenticated but not encrypted, 441 # it must also be passed in on decryption. 442 encryptor.authenticate_additional_data(associated_data) 443 444 # Encrypt the plaintext and get the associated ciphertext. 445 # GCM does not require padding. 446 ciphertext = encryptor.update(plaintext) + encryptor.finalize() 447 448 return (iv, ciphertext, encryptor.tag) 449 450 def decrypt(key, associated_data, iv, ciphertext, tag): 451 # Construct a Cipher object, with the key, iv, and additionally the 452 # GCM tag used for authenticating the message. 453 decryptor = Cipher( 454 algorithms.AES(key), 455 modes.GCM(iv, tag), 456 ).decryptor() 457 458 # We put associated_data back in or the tag will fail to verify 459 # when we finalize the decryptor. 460 decryptor.authenticate_additional_data(associated_data) 461 462 # Decryption gets us the authenticated plaintext. 463 # If the tag does not match an InvalidTag exception will be raised. 464 return decryptor.update(ciphertext) + decryptor.finalize() 465 466 iv, ciphertext, tag = encrypt( 467 key, 468 b"a secret message!", 469 b"authenticated but not encrypted payload" 470 ) 471 472 print(decrypt( 473 key, 474 b"authenticated but not encrypted payload", 475 iv, 476 ciphertext, 477 tag 478 )) 479 480 .. testoutput:: 481 482 b'a secret message!' 483 484.. class:: XTS(tweak) 485 486 .. versionadded:: 2.1 487 488 .. warning:: 489 490 XTS mode is meant for disk encryption and should not be used in other 491 contexts. ``cryptography`` only supports XTS mode with 492 :class:`~cryptography.hazmat.primitives.ciphers.algorithms.AES`. 493 494 .. note:: 495 496 AES XTS keys are double length. This means that to do AES-128 497 encryption in XTS mode you need a 256-bit key. Similarly, AES-256 498 requires passing a 512-bit key. AES 192 is not supported in XTS mode. 499 500 XTS (XEX-based tweaked-codebook mode with ciphertext stealing) is a mode 501 of operation for the AES block cipher that is used for `disk encryption`_. 502 503 **This mode does not require padding.** 504 505 :param tweak: The tweak is a 16 byte value typically derived from 506 something like the disk sector number. A given ``(tweak, key)`` pair 507 should not be reused, although doing so is less catastrophic than 508 in CTR mode. 509 :type tweak: :term:`bytes-like` 510 511Insecure modes 512-------------- 513 514.. warning:: 515 516 These modes are insecure. New applications should never make use of them, 517 and existing applications should strongly consider migrating away. 518 519 520.. class:: ECB() 521 522 ECB (Electronic Code Book) is the simplest mode of operation for block 523 ciphers. Each block of data is encrypted in the same way. This means 524 identical plaintext blocks will always result in identical ciphertext 525 blocks, which can leave `significant patterns in the output`_. 526 527 **Padding is required when using this mode.** 528 529Interfaces 530~~~~~~~~~~ 531 532.. currentmodule:: cryptography.hazmat.primitives.ciphers 533 534.. class:: CipherContext 535 536 When calling ``encryptor()`` or ``decryptor()`` on a ``Cipher`` object 537 the result will conform to the ``CipherContext`` interface. You can then 538 call ``update(data)`` with data until you have fed everything into the 539 context. Once that is done call ``finalize()`` to finish the operation and 540 obtain the remainder of the data. 541 542 Block ciphers require that the plaintext or ciphertext always be a multiple 543 of their block size. Because of that **padding** is sometimes required to 544 make a message the correct size. ``CipherContext`` will not automatically 545 apply any padding; you'll need to add your own. For block ciphers the 546 recommended padding is 547 :class:`~cryptography.hazmat.primitives.padding.PKCS7`. If you are using a 548 stream cipher mode (such as 549 :class:`~cryptography.hazmat.primitives.ciphers.modes.CTR`) you don't have 550 to worry about this. 551 552 .. method:: update(data) 553 554 :param data: The data you wish to pass into the context. 555 :type data: :term:`bytes-like` 556 :return bytes: Returns the data that was encrypted or decrypted. 557 :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize` 558 559 When the ``Cipher`` was constructed in a mode that turns it into a 560 stream cipher (e.g. 561 :class:`~cryptography.hazmat.primitives.ciphers.modes.CTR`), this will 562 return bytes immediately, however in other modes it will return chunks 563 whose size is determined by the cipher's block size. 564 565 .. method:: update_into(data, buf) 566 567 .. versionadded:: 1.8 568 569 .. warning:: 570 571 This method allows you to avoid a memory copy by passing a writable 572 buffer and reading the resulting data. You are responsible for 573 correctly sizing the buffer and properly handling the data. This 574 method should only be used when extremely high performance is a 575 requirement and you will be making many small calls to 576 ``update_into``. 577 578 :param data: The data you wish to pass into the context. 579 :type data: :term:`bytes-like` 580 :param buf: A writable Python buffer that the data will be written 581 into. This buffer should be ``len(data) + n - 1`` bytes where ``n`` 582 is the block size (in bytes) of the cipher and mode combination. 583 :return int: Number of bytes written. 584 :raises NotImplementedError: This is raised if the version of ``cffi`` 585 used is too old (this can happen on older PyPy releases). 586 :raises ValueError: This is raised if the supplied buffer is too small. 587 588 .. doctest:: 589 590 >>> import os 591 >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes 592 >>> key = os.urandom(32) 593 >>> iv = os.urandom(16) 594 >>> cipher = Cipher(algorithms.AES(key), modes.CBC(iv)) 595 >>> encryptor = cipher.encryptor() 596 >>> # the buffer needs to be at least len(data) + n - 1 where n is cipher/mode block size in bytes 597 >>> buf = bytearray(31) 598 >>> len_encrypted = encryptor.update_into(b"a secret message", buf) 599 >>> # get the ciphertext from the buffer reading only the bytes written to it (len_encrypted) 600 >>> ct = bytes(buf[:len_encrypted]) + encryptor.finalize() 601 >>> decryptor = cipher.decryptor() 602 >>> len_decrypted = decryptor.update_into(ct, buf) 603 >>> # get the plaintext from the buffer reading only the bytes written (len_decrypted) 604 >>> bytes(buf[:len_decrypted]) + decryptor.finalize() 605 b'a secret message' 606 607 .. method:: finalize() 608 609 :return bytes: Returns the remainder of the data. 610 :raises ValueError: This is raised when the data provided isn't 611 a multiple of the algorithm's block size. 612 613 Once ``finalize`` is called this object can no longer be used and 614 :meth:`update` and :meth:`finalize` will raise an 615 :class:`~cryptography.exceptions.AlreadyFinalized` exception. 616 617.. class:: AEADCipherContext 618 619 When calling ``encryptor`` or ``decryptor`` on a ``Cipher`` object 620 with an AEAD mode (e.g. 621 :class:`~cryptography.hazmat.primitives.ciphers.modes.GCM`) the result will 622 conform to the ``AEADCipherContext`` and ``CipherContext`` interfaces. If 623 it is an encryption or decryption context it will additionally be an 624 ``AEADEncryptionContext`` or ``AEADDecryptionContext`` instance, 625 respectively. ``AEADCipherContext`` contains an additional method 626 :meth:`authenticate_additional_data` for adding additional authenticated 627 but unencrypted data (see note below). You should call this before calls to 628 ``update``. When you are done call ``finalize`` to finish the operation. 629 630 .. note:: 631 632 In AEAD modes all data passed to ``update()`` will be both encrypted 633 and authenticated. Do not pass encrypted data to the 634 ``authenticate_additional_data()`` method. It is meant solely for 635 additional data you may want to authenticate but leave unencrypted. 636 637 .. method:: authenticate_additional_data(data) 638 639 :param data: Any data you wish to authenticate but not encrypt. 640 :type data: :term:`bytes-like` 641 :raises: :class:`~cryptography.exceptions.AlreadyFinalized` 642 643.. class:: AEADEncryptionContext 644 645 When creating an encryption context using ``encryptor`` on a ``Cipher`` 646 object with an AEAD mode such as 647 :class:`~cryptography.hazmat.primitives.ciphers.modes.GCM` an object 648 conforming to both the ``AEADEncryptionContext`` and ``AEADCipherContext`` 649 interfaces will be returned. This interface provides one 650 additional attribute ``tag``. ``tag`` can only be obtained after 651 ``finalize`` has been called. 652 653 .. attribute:: tag 654 655 :return bytes: Returns the tag value as bytes. 656 :raises: :class:`~cryptography.exceptions.NotYetFinalized` if called 657 before the context is finalized. 658 659.. class:: AEADDecryptionContext 660 661 .. versionadded:: 1.9 662 663 When creating an encryption context using ``decryptor`` on a ``Cipher`` 664 object with an AEAD mode such as 665 :class:`~cryptography.hazmat.primitives.ciphers.modes.GCM` an object 666 conforming to both the ``AEADDecryptionContext`` and ``AEADCipherContext`` 667 interfaces will be returned. This interface provides one additional method 668 :meth:`finalize_with_tag` that allows passing the authentication tag for 669 validation after the ciphertext has been decrypted. 670 671 .. method:: finalize_with_tag(tag) 672 673 :param bytes tag: The tag bytes to verify after decryption. 674 :return bytes: Returns the remainder of the data. 675 :raises ValueError: This is raised when the data provided isn't 676 a multiple of the algorithm's block size, if ``min_tag_length`` is 677 less than 4, or if ``len(tag) < min_tag_length``. 678 ``min_tag_length`` is an argument to the ``GCM`` constructor. 679 680 If the authentication tag was not already supplied to the constructor 681 of the :class:`~cryptography.hazmat.primitives.ciphers.modes.GCM` mode 682 object, this method must be used instead of 683 :meth:`~cryptography.hazmat.primitives.ciphers.CipherContext.finalize`. 684 685.. class:: CipherAlgorithm 686 687 A named symmetric encryption algorithm. 688 689 .. attribute:: name 690 691 :type: str 692 693 The standard name for the mode, for example, "AES", "Camellia", or 694 "Blowfish". 695 696 .. attribute:: key_size 697 698 :type: int 699 700 The number of :term:`bits` in the key being used. 701 702 703.. class:: BlockCipherAlgorithm 704 705 A block cipher algorithm. 706 707 .. attribute:: block_size 708 709 :type: int 710 711 The number of :term:`bits` in a block. 712 713Interfaces used by the symmetric cipher modes described in 714:ref:`Symmetric Encryption Modes <symmetric-encryption-modes>`. 715 716.. currentmodule:: cryptography.hazmat.primitives.ciphers.modes 717 718.. class:: Mode 719 720 A named cipher mode. 721 722 .. attribute:: name 723 724 :type: str 725 726 This should be the standard shorthand name for the mode, for example 727 Cipher-Block Chaining mode is "CBC". 728 729 The name may be used by a backend to influence the operation of a 730 cipher in conjunction with the algorithm's name. 731 732 .. method:: validate_for_algorithm(algorithm) 733 734 :param cryptography.hazmat.primitives.ciphers.CipherAlgorithm algorithm: 735 736 Checks that the combination of this mode with the provided algorithm 737 meets any necessary invariants. This should raise an exception if they 738 are not met. 739 740 For example, the 741 :class:`~cryptography.hazmat.primitives.ciphers.modes.CBC` mode uses 742 this method to check that the provided initialization vector's length 743 matches the block size of the algorithm. 744 745 746.. class:: ModeWithInitializationVector 747 748 A cipher mode with an initialization vector. 749 750 .. attribute:: initialization_vector 751 752 :type: :term:`bytes-like` 753 754 Exact requirements of the initialization are described by the 755 documentation of individual modes. 756 757 758.. class:: ModeWithNonce 759 760 A cipher mode with a nonce. 761 762 .. attribute:: nonce 763 764 :type: :term:`bytes-like` 765 766 Exact requirements of the nonce are described by the documentation of 767 individual modes. 768 769 770.. class:: ModeWithAuthenticationTag 771 772 A cipher mode with an authentication tag. 773 774 .. attribute:: tag 775 776 :type: :term:`bytes-like` 777 778 Exact requirements of the tag are described by the documentation of 779 individual modes. 780 781 782.. class:: ModeWithTweak 783 784 .. versionadded:: 2.1 785 786 A cipher mode with a tweak. 787 788 .. attribute:: tweak 789 790 :type: :term:`bytes-like` 791 792 Exact requirements of the tweak are described by the documentation of 793 individual modes. 794 795Exceptions 796~~~~~~~~~~ 797 798.. currentmodule:: cryptography.exceptions 799 800 801.. class:: InvalidTag 802 803 This is raised if an authenticated encryption tag fails to verify during 804 decryption. 805 806 807 808.. _`described by Colin Percival`: https://www.daemonology.net/blog/2009-06-11-cryptographic-right-answers.html 809.. _`recommends a 96-bit IV length`: https://csrc.nist.gov/publications/detail/sp/800-38d/final 810.. _`NIST SP-800-38D`: https://csrc.nist.gov/publications/detail/sp/800-38d/final 811.. _`Communications Security Establishment`: https://www.cse-cst.gc.ca 812.. _`encrypt`: https://ssd.eff.org/en/module/what-should-i-know-about-encryption 813.. _`CRYPTREC`: https://www.cryptrec.go.jp/english/ 814.. _`significant patterns in the output`: https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Electronic_codebook_(ECB) 815.. _`International Data Encryption Algorithm`: https://en.wikipedia.org/wiki/International_Data_Encryption_Algorithm 816.. _`OpenPGP`: https://www.openpgp.org/ 817.. _`disk encryption`: https://en.wikipedia.org/wiki/Disk_encryption_theory#XTS 818