OCB3 support (#6607)

* OCB3 support in aead package

* improve comment

1 files changed, 72 insertions, 0 deletions

diff --git a/docs/hazmat/primitives/aead.rst b/docs/hazmat/primitives/aead.rst
index 7d84e0bcc..787b50d7e 100644
--- a/docs/hazmat/primitives/aead.rst
+++ b/docs/hazmat/primitives/aead.rst
@@ -156,6 +156,78 @@ also support providing integrity for associated data which is not encrypted.
             when the ciphertext has been changed, but will also occur when the
             key, nonce, or associated data are wrong.
 
+.. class:: AESOCB3(key)
+
+    .. versionadded:: 36.0
+
+    The OCB3 construction is defined in :rfc:`7253`. It is an AEAD mode
+    that offers strong integrity guarantees and good performance.
+
+    :param key: A 128, 192, or 256-bit key. This **must** be kept secret.
+    :type key: :term:`bytes-like`
+
+    :raises cryptography.exceptions.UnsupportedAlgorithm: If the version of
+        OpenSSL does not support AES-OCB3.
+
+    .. doctest::
+
+        >>> import os
+        >>> from cryptography.hazmat.primitives.ciphers.aead import AESOCB3
+        >>> data = b"a secret message"
+        >>> aad = b"authenticated but unencrypted data"
+        >>> key = AESOCB3.generate_key(bit_length=128)
+        >>> aesocb = AESOCB3(key)
+        >>> nonce = os.urandom(12)
+        >>> ct = aesocb.encrypt(nonce, data, aad)
+        >>> aesocb.decrypt(nonce, ct, aad)
+        b'a secret message'
+
+    .. classmethod:: generate_key(bit_length)
+
+        Securely generates a random AES-OCB3 key.
+
+        :param bit_length: The bit length of the key to generate. Must be
+            128, 192, or 256.
+
+        :returns bytes: The generated 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 and authenticates the ``data`` provided as well as
+        authenticating the ``associated_data``.  The output of this can be
+        passed directly to the ``decrypt`` method.
+
+        :param nonce: A 12 byte value. **NEVER REUSE A NONCE** with a key.
+        :type nonce: :term:`bytes-like`
+        :param bytes data: The data to encrypt.
+        :param bytes associated_data: Additional data that should be
+            authenticated with the key, but is not encrypted. Can be ``None``.
+        :returns bytes: The ciphertext bytes with the 16 byte tag appended.
+        :raises OverflowError: If ``data`` or ``associated_data`` is larger
+            than 2\ :sup:`31` - 1 bytes.
+
+    .. 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 nonce: A 12 byte value. **NEVER REUSE A NONCE** with a key.
+        :type nonce: :term:`bytes-like`
+        :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.
+
 .. class:: AESCCM(key, tag_length=16)
 
     .. versionadded:: 2.0