Add AES-256-GCM support to the HPKE implementation (#14397)

Add AES_256_GCM (AEAD ID 0x0002) as an AEAD option for HPKE, alongside
the existing AES-128-GCM and ChaCha20Poly1305 options. This completes
support for all three AEAD algorithms defined in RFC 9180.

https://claude.ai/code/session_013SgdaoQ9Jn8qAYqkNPWByV

Co-authored-by: Claude <noreply@anthropic.com>

Author: alex

docs/hazmat/primitives/hpke.rst

@@ -9,9 +9,6 @@ HPKE is a standard for public key encryption that combines a Key Encapsulation
 Mechanism (KEM), a Key Derivation Function (KDF), and an Authenticated
 Encryption with Associated Data (AEAD) scheme. It is defined in :rfc:`9180`.
 
-This implementation supports Base mode with DHKEM(X25519, HKDF-SHA256),
-HKDF-SHA256, and either AES-128-GCM or ChaCha20Poly1305.
-
 HPKE provides authenticated encryption: the recipient can be certain that the
 message was encrypted by someone who knows the recipient's public key, but
 the sender is anonymous. Each call to :meth:`Suite.encrypt` generates a fresh
@@ -100,6 +97,10 @@ specifying auxiliary authenticated information.
 
         AES-128-GCM
 
+    .. attribute:: AES_256_GCM
+
+        AES-256-GCM
+
     .. attribute:: CHACHA20_POLY1305
 
         ChaCha20Poly1305

src/cryptography/hazmat/bindings/_rust/openssl/hpke.pyi

@@ -14,6 +14,7 @@ class KDF:
 
 class AEAD:
     AES_128_GCM: AEAD
+    AES_256_GCM: AEAD
     CHACHA20_POLY1305: AEAD
 
 class Suite:

src/rust/src/backend/hpke.rs

@@ -31,6 +31,11 @@ mod aead_params {
     pub const AES_128_GCM_NN: usize = 12;
     pub const AES_128_GCM_NT: usize = 16;
 
+    pub const AES_256_GCM_ID: u16 = 0x0002;
+    pub const AES_256_GCM_NK: usize = 32;
+    pub const AES_256_GCM_NN: usize = 12;
+    pub const AES_256_GCM_NT: usize = 16;
+
     pub const CHACHA20_POLY1305_ID: u16 = 0x0003;
     pub const CHACHA20_POLY1305_NK: usize = 32;
     pub const CHACHA20_POLY1305_NN: usize = 12;
@@ -96,34 +101,39 @@ impl KDF {
 #[derive(Clone, PartialEq, Eq, Hash)]
 pub(crate) enum AEAD {
     AES_128_GCM,
+    AES_256_GCM,
     CHACHA20_POLY1305,
 }
 
 impl AEAD {
     fn id(&self) -> u16 {
         match self {
             AEAD::AES_128_GCM => aead_params::AES_128_GCM_ID,
+            AEAD::AES_256_GCM => aead_params::AES_256_GCM_ID,
             AEAD::CHACHA20_POLY1305 => aead_params::CHACHA20_POLY1305_ID,
         }
     }
 
     fn key_length(&self) -> usize {
         match self {
             AEAD::AES_128_GCM => aead_params::AES_128_GCM_NK,
+            AEAD::AES_256_GCM => aead_params::AES_256_GCM_NK,
             AEAD::CHACHA20_POLY1305 => aead_params::CHACHA20_POLY1305_NK,
         }
     }
 
     fn nonce_length(&self) -> usize {
         match self {
             AEAD::AES_128_GCM => aead_params::AES_128_GCM_NN,
+            AEAD::AES_256_GCM => aead_params::AES_256_GCM_NN,
             AEAD::CHACHA20_POLY1305 => aead_params::CHACHA20_POLY1305_NN,
         }
     }
 
     fn tag_length(&self) -> usize {
         match self {
             AEAD::AES_128_GCM => aead_params::AES_128_GCM_NT,
+            AEAD::AES_256_GCM => aead_params::AES_256_GCM_NT,
             AEAD::CHACHA20_POLY1305 => aead_params::CHACHA20_POLY1305_NT,
         }
     }
@@ -306,7 +316,7 @@ impl Suite {
         let key_obj = key.clone().unbind().into_any();
         let nonce_buf = CffiBuf::from_bytes(py, nonce.as_bytes());
         match &self.aead {
-            AEAD::AES_128_GCM => {
+            AEAD::AES_128_GCM | AEAD::AES_256_GCM => {
                 let cipher = AesGcm::new(py, key_obj)?;
                 cipher.encrypt(py, nonce_buf, plaintext, aad)
             }
@@ -328,7 +338,7 @@ impl Suite {
         let key_obj = key.clone().unbind().into_any();
         let nonce_buf = CffiBuf::from_bytes(py, nonce.as_bytes());
         match &self.aead {
-            AEAD::AES_128_GCM => {
+            AEAD::AES_128_GCM | AEAD::AES_256_GCM => {
                 let cipher = AesGcm::new(py, key_obj)?;
                 cipher.decrypt(py, nonce_buf, CffiBuf::from_bytes(py, ciphertext), aad)
             }

tests/hazmat/primitives/test_hpke.py

@@ -2,6 +2,7 @@
 # 2.0, and the BSD License. See the LICENSE file in the root of this repository
 # for complete details.
 
+import itertools
 import json
 import os
 
@@ -21,11 +22,13 @@
 
 X25519_ENC_LENGTH = 32
 
-SUPPORTED_SUITES = [
-    (KEM.X25519, KDF.HKDF_SHA256, AEAD.AES_128_GCM),
-    (KEM.X25519, KDF.HKDF_SHA256, AEAD.CHACHA20_POLY1305),
-    (KEM.X25519, KDF.HKDF_SHA512, AEAD.AES_128_GCM),
-]
+SUPPORTED_SUITES = list(
+    itertools.product(
+        [KEM.X25519],
+        [KDF.HKDF_SHA256, KDF.HKDF_SHA512],
+        [AEAD.AES_128_GCM, AEAD.AES_256_GCM, AEAD.CHACHA20_POLY1305],
+    )
+)
 
 
 @pytest.mark.supported(
@@ -232,6 +235,7 @@ def test_vector_decryption(self, subtests):
         }
         aead_map = {
             0x0001: AEAD.AES_128_GCM,
+            0x0002: AEAD.AES_256_GCM,
             0x0003: AEAD.CHACHA20_POLY1305,
         }