diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/hazmat/primitives/aead.rst | 79 | ||||
| -rw-r--r-- | docs/hazmat/primitives/index.rst | 1 | ||||
| -rw-r--r-- | docs/spelling_wordlist.txt | 1 |
3 files changed, 81 insertions, 0 deletions
diff --git a/docs/hazmat/primitives/aead.rst b/docs/hazmat/primitives/aead.rst new file mode 100644 index 00000000..54343b86 --- /dev/null +++ b/docs/hazmat/primitives/aead.rst @@ -0,0 +1,79 @@ +.. hazmat:: + + +Authenticated encryption +======================== + +.. module:: cryptography.hazmat.primitives.ciphers.aead + +Authenticated encryption with associated data (AEAD) are encryption schemes +which provide both confidentiality and integrity for their ciphertext. They +also support providing integrity for associated data which is not encrypted. + +.. class:: ChaCha20Poly1305(key) + + .. versionadded:: 2.0 + + The ChaCha20Poly1305 construction is defined in :rfc:`7539` section 2.8. + It is a stream cipher combined with a MAC that offers strong integrity + guarantees. + + :param bytes key: A 32-byte key. This **must** be kept secret. + + :raises cryptography.exceptions.UnsupportedAlgorithm: If the version of + OpenSSL does not support ChaCha20Poly1305. + + .. doctest:: + + >>> import os + >>> from cryptography.hazmat.primitives.ciphers.aead import ChaCha20Poly1305 + >>> data = b"a secret message" + >>> aad = b"authenticated but unencrypted data" + >>> key = ChaCha20Poly1305.generate_key() + >>> chacha = ChaCha20Poly1305(key) + >>> nonce = os.urandom(12) + >>> ct = chacha.encrypt(nonce, data, aad) + >>> chacha.decrypt(nonce, ct, aad) + 'a secret message' + + .. classmethod:: generate_key() + + Securely generates a random ChaCha20Poly1305 key. + + :returns bytes: A 32 byte key. + + .. method:: encrypt(nonce, data, associated_data) + + .. warning:: + + Reuse of a ``nonce`` with a given ``key`` compromises the security + of any message with that ``nonce`` and ``key`` pair. + + Encrypts the ``data`` provided and authenticates the + ``associated_data``. The output of this can be passed directly + to the ``decrypt`` method. + + :param bytes nonce: A 12 byte value. **NEVER REUSE A NONCE** with a + key. + :param bytes data: The data to encrypt. + :param bytes associated_data: Additional data that should be + authenticated with the key, but does not need to be encrypted. Can + be ``None``. + :returns bytes: The ciphertext bytes with the 16 byte tag appended. + + .. method:: decrypt(nonce, data, associated_data) + + Decrypts the ``data`` and authenticates the ``associated_data``. If you + called encrypt with ``associated_data`` you must pass the same + ``associated_data`` in decrypt or the integrity check will fail. + + :param bytes nonce: A 12 byte value. **NEVER REUSE A NONCE** with a + key. + :param bytes data: The data to decrypt (with tag appended). + :param bytes associated_data: Additional data to authenticate. Can be + ``None`` if none was passed during encryption. + :returns bytes: The original plaintext. + :raises cryptography.exceptions.InvalidTag: If the authentication tag + doesn't validate this exception will be raised. This will occur + when the ciphertext has been changed, but will also occur when the + key, nonce, or associated data are wrong. diff --git a/docs/hazmat/primitives/index.rst b/docs/hazmat/primitives/index.rst index 78beb3d9..72e5b26c 100644 --- a/docs/hazmat/primitives/index.rst +++ b/docs/hazmat/primitives/index.rst @@ -6,6 +6,7 @@ Primitives .. toctree:: :maxdepth: 1 + aead asymmetric/index constant-time key-derivation-functions diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt index b3303a43..d9921a0e 100644 --- a/docs/spelling_wordlist.txt +++ b/docs/spelling_wordlist.txt @@ -19,6 +19,7 @@ cryptographic cryptographically Debian decrypt +Decrypts decrypted decrypting DER |