Track ChaCha20 32-bit counter and error on overflow

CHANGELOG.rst

@@ -12,6 +12,13 @@ Changelog
   We now only publish ``arm64`` wheels for macOS.
 * **BACKWARDS INCOMPATIBLE:** Support for 32-bit Windows has been removed.
   Users should move to a 64-bit Python installation.
+* **BACKWARDS INCOMPATIBLE:** :class:`~cryptography.hazmat.primitives.ciphers.algorithms.ChaCha20`
+  now treats the first 4 bytes of the ``nonce`` as a 32-bit little-endian block
+  counter (as defined in :rfc:`7539`) and tracks the number of bytes processed.
+  Attempting to encrypt or decrypt more data than the counter allows before it
+  would overflow now raises a :class:`ValueError` rather than silently diverging
+  from RFC 7539. Setting the counter portion of the ``nonce`` to zero allows
+  encrypting up to 256 GiB with a given nonce.
 * Fixed cross-compilation of the CFFI bindings when ``PYO3_CROSS_LIB_DIR``
   is set. The build now derives the Python include directory from
   ``PYO3_CROSS_LIB_DIR`` instead of querying the host interpreter, which

docs/development/test-vectors.rst

@@ -1173,8 +1173,7 @@ Symmetric ciphers
 * CAST5 (ECB) from :rfc:`2144`.
 * CAST5 (CBC, CFB, OFB) generated by this project.
   See: :doc:`/development/custom-vectors/cast5`
-* ChaCha20 from :rfc:`7539` and generated by this project.
-  See: :doc:`/development/custom-vectors/chacha20`
+* ChaCha20 from :rfc:`7539`.
 * ChaCha20Poly1305 from :rfc:`7539`, `OpenSSL's evpciph.txt`_, and the
   `BoringSSL ChaCha20Poly1305 tests`_.
 * IDEA (ECB) from the `NESSIE IDEA vectors`_ created by `NESSIE`_.
@@ -1220,7 +1219,6 @@ Created Vectors
     custom-vectors/aes-192-gcm-siv
     custom-vectors/arc4
     custom-vectors/cast5
-    custom-vectors/chacha20
     custom-vectors/idea
     custom-vectors/seed
     custom-vectors/hkdf

docs/hazmat/primitives/symmetric-encryption.rst

@@ -146,11 +146,8 @@ Algorithms
         :class:`~cryptography.hazmat.primitives.ciphers.aead.ChaCha20Poly1305`
         does this for you.
 
-    ChaCha20 is a stream cipher used in several IETF protocols. While it is
-    standardized in :rfc:`7539`, **this implementation is not RFC-compliant**.
-    This implementation uses a ``64`` :term:`bits` counter and a ``64``
-    :term:`bits` nonce as defined in the `original version`_ of the algorithm,
-    rather than the ``32/96`` counter/nonce split defined in :rfc:`7539`.
+    ChaCha20 is a stream cipher used in several IETF protocols. It is
+    standardized in :rfc:`7539`.
 
     :param key: The secret key. This must be kept secret. ``256``
         :term:`bits` (32 bytes) in length.
@@ -161,30 +158,30 @@ Algorithms
         nonce with the same key compromises the security of every message
         encrypted with that key. The nonce does not need to be kept secret
         and may be included with the ciphertext. This must be ``128``
-        :term:`bits` in length. The 128-bit value is a concatenation of the
-        8-byte little-endian counter and the 8-byte nonce.
+        :term:`bits` in length. The 128-bit value is a concatenation of a
+        4-byte little-endian block counter followed by a 12-byte nonce, as
+        described in :rfc:`7539`.
     :type nonce: :term:`bytes-like`
 
     .. note::
 
-        In the `original version`_ of the algorithm the nonce is defined as a
-        64-bit value that is later concatenated with a block counter (encoded
-        as a 64-bit little-endian). If you have a separate nonce and block
-        counter you will need to concatenate it yourself before passing it.
-        For example, if you have an initial block counter of 2 and a 64-bit
-        nonce the concatenated nonce would be
-        ``struct.pack("<Q", 2) + nonce``.
-
+        The block counter occupies the first 4 bytes of the 128-bit value and
+        is a 32-bit little-endian integer. Each ChaCha20 block encrypts 64
+        bytes, so an initial counter value of ``n`` allows up to
+        ``(2 ** 32 - n) * 64`` bytes to be encrypted before the counter would
+        overflow. We recommend setting the counter portion to zero, which
+        allows encrypting up to 256 GiB with a given nonce. Attempting to
+        encrypt or decrypt more data than the counter allows raises a
+        :class:`ValueError`.
 
     .. doctest::
 
-        >>> import struct, os
+        >>> import os
         >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
         >>> key = os.urandom(32)
-        >>> nonce = os.urandom(8)
-        >>> counter = 0
-        >>> full_nonce = struct.pack("<Q", counter) + nonce
-        >>> algorithm = algorithms.ChaCha20(key, full_nonce)
+        >>> counter = b"\x00\x00\x00\x00"
+        >>> nonce = counter + os.urandom(12)
+        >>> algorithm = algorithms.ChaCha20(key, nonce)
         >>> cipher = Cipher(algorithm, mode=None)
         >>> encryptor = cipher.encryptor()
         >>> ct = encryptor.update(b"a secret message")
@@ -862,7 +859,6 @@ Exceptions
 .. _`Communications Security Establishment`: https://www.cse-cst.gc.ca
 .. _`encrypt`: https://ssd.eff.org/en/module/what-should-i-know-about-encryption
 .. _`CRYPTREC`: https://www.cryptrec.go.jp/en/
-.. _`original version`: https://en.wikipedia.org/wiki/Salsa20#ChaCha_variant
 .. _`significant patterns in the output`: https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Electronic_codebook_(ECB)
 .. _`International Data Encryption Algorithm`: https://en.wikipedia.org/wiki/International_Data_Encryption_Algorithm
 .. _`OpenPGP`: https://www.openpgp.org/

docs/spelling_wordlist.txt

@@ -69,6 +69,7 @@ Fernet
 fernet
 FIPS
 Gaynor
+GiB
 Google
 Graviola
 hazmat