feat: add DTLS 1.2 ChaCha20 and X25519 support

Author: HMBSbige

src/buffer.rs

@@ -38,7 +38,7 @@ impl BufferPool {
 }
 
 impl fmt::Debug for BufferPool {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         f.debug_struct("BufferPool")
             .field("free", &self.free.len())
             .finish()
@@ -118,7 +118,7 @@ impl AsMut<[u8]> for Buf {
 }
 
 impl fmt::Debug for Buf {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         f.debug_struct("Buf").field("len", &self.0.len()).finish()
     }
 }

src/config.rs

@@ -198,15 +198,6 @@ impl Config {
                 None => true,
             })
     }
-
-    /// Allowed key exchange groups for DTLS 1.2.
-    ///
-    /// Like [`kx_groups`](Self::kx_groups) but additionally restricted to
-    /// groups that DTLS 1.2 supports (currently P-256 and P-384).
-    pub fn dtls12_kx_groups(&self) -> impl Iterator<Item = &'static dyn SupportedKxGroup> + '_ {
-        self.kx_groups()
-            .filter(|kx| matches!(kx.name(), NamedGroup::Secp256r1 | NamedGroup::Secp384r1))
-    }
 }
 
 /// Builder for [`Config`]. See each setter for defaults.
@@ -446,13 +437,13 @@ impl ConfigBuilder {
         };
         if dtls12_count > 0 {
             let dtls12_kx_count = crypto_provider
-                .supported_dtls12_kx_groups()
+                .supported_kx_groups()
                 .filter(|kx| filtered_kx(kx))
                 .count();
             if dtls12_kx_count == 0 {
                 return Err(Error::ConfigError(
                     "DTLS 1.2 cipher suites are enabled but no compatible key exchange \
-                     groups remain after filtering. DTLS 1.2 requires P-256 or P-384."
+                     groups remain after filtering."
                         .to_string(),
                 ));
             }
@@ -635,23 +626,15 @@ mod tests {
     }
 
     #[test]
-    fn x25519_only_rejected_for_dtls12() {
-        // X25519 is not yet supported for DTLS 1.2, so filtering to X25519-only
-        // while DTLS 1.2 suites are enabled should fail.
-        match Config::builder()
+    fn x25519_only_accepted_for_dtls12() {
+        // X25519 is supported for DTLS 1.2 and should be accepted.
+        let config = Config::builder()
             .dtls13_cipher_suites(&[])
             .kx_groups(&[NamedGroup::X25519])
             .build()
-        {
-            Err(Error::ConfigError(msg)) => {
-                assert!(
-                    msg.contains("DTLS 1.2") && msg.contains("P-256 or P-384"),
-                    "error should mention DTLS 1.2 and required groups: {msg}"
-                )
-            }
-            Err(other) => panic!("expected ConfigError, got: {other:?}"),
-            Ok(_) => panic!("expected error for X25519-only with DTLS 1.2"),
-        }
+            .expect("X25519-only should be accepted for DTLS 1.2");
+        let groups: Vec<_> = config.kx_groups().map(|g| g.name()).collect();
+        assert_eq!(groups, &[NamedGroup::X25519]);
     }
 
     #[test]
@@ -667,11 +650,15 @@ mod tests {
     }
 
     #[test]
-    fn dtls12_kx_groups_excludes_x25519() {
+    fn kx_groups_match_provider_when_unfiltered() {
         let config = Config::default();
-        let dtls12_groups: Vec<_> = config.dtls12_kx_groups().map(|g| g.name()).collect();
-        assert!(!dtls12_groups.contains(&NamedGroup::X25519));
-        assert!(dtls12_groups.contains(&NamedGroup::Secp256r1));
+        let from_config: Vec<_> = config.kx_groups().map(|g| g.name()).collect();
+        let from_provider: Vec<_> = config
+            .crypto_provider()
+            .supported_kx_groups()
+            .map(|g| g.name())
+            .collect();
+        assert_eq!(from_config, from_provider);
     }
 
     #[test]

src/crypto/aws_lc_rs/cipher_suite.rs

@@ -159,6 +159,14 @@ impl SupportedDtls12CipherSuite for Aes128GcmSha256 {
         (0, 16, 4) // (mac_key_len, enc_key_len, fixed_iv_len)
     }
 
+    fn explicit_nonce_len(&self) -> usize {
+        8
+    }
+
+    fn tag_len(&self) -> usize {
+        16
+    }
+
     fn create_cipher(&self, key: &[u8]) -> Result<Box<dyn Cipher>, String> {
         Ok(Box::new(AesGcm::new(key)?))
     }
@@ -181,18 +189,60 @@ impl SupportedDtls12CipherSuite for Aes256GcmSha384 {
         (0, 32, 4) // (mac_key_len, enc_key_len, fixed_iv_len)
     }
 
+    fn explicit_nonce_len(&self) -> usize {
+        8
+    }
+
+    fn tag_len(&self) -> usize {
+        16
+    }
+
     fn create_cipher(&self, key: &[u8]) -> Result<Box<dyn Cipher>, String> {
         Ok(Box::new(AesGcm::new(key)?))
     }
 }
 
+/// TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 cipher suite.
+#[derive(Debug)]
+struct ChaCha20Poly1305Sha256;
+
+impl SupportedDtls12CipherSuite for ChaCha20Poly1305Sha256 {
+    fn suite(&self) -> Dtls12CipherSuite {
+        Dtls12CipherSuite::ECDHE_ECDSA_CHACHA20_POLY1305_SHA256
+    }
+
+    fn hash_algorithm(&self) -> HashAlgorithm {
+        HashAlgorithm::SHA256
+    }
+
+    fn key_lengths(&self) -> (usize, usize, usize) {
+        (0, 32, 12) // (mac_key_len, enc_key_len, fixed_iv_len)
+    }
+
+    fn explicit_nonce_len(&self) -> usize {
+        0
+    }
+
+    fn tag_len(&self) -> usize {
+        16
+    }
+
+    fn create_cipher(&self, key: &[u8]) -> Result<Box<dyn Cipher>, String> {
+        Ok(Box::new(ChaCha20Poly1305Cipher::new(key)?))
+    }
+}
+
 /// Static instances of supported DTLS 1.2 cipher suites.
 static AES_128_GCM_SHA256: Aes128GcmSha256 = Aes128GcmSha256;
 static AES_256_GCM_SHA384: Aes256GcmSha384 = Aes256GcmSha384;
+static CHACHA20_POLY1305_SHA256: ChaCha20Poly1305Sha256 = ChaCha20Poly1305Sha256;
 
 /// All supported DTLS 1.2 cipher suites.
-pub(super) static ALL_CIPHER_SUITES: &[&dyn SupportedDtls12CipherSuite] =
-    &[&AES_128_GCM_SHA256, &AES_256_GCM_SHA384];
+pub(super) static ALL_CIPHER_SUITES: &[&dyn SupportedDtls12CipherSuite] = &[
+    &AES_128_GCM_SHA256,
+    &AES_256_GCM_SHA384,
+    &CHACHA20_POLY1305_SHA256,
+];
 
 // ============================================================================
 // DTLS 1.3 Cipher Suites

src/crypto/aws_lc_rs/mod.rs

@@ -77,9 +77,11 @@ use super::CryptoProvider;
 ///
 /// - `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256` (0xC02B)
 /// - `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384` (0xC02C)
+/// - `TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256` (0xCCA9)
 ///
 /// # Supported Key Exchange Groups
 ///
+/// - `x25519` (X25519 / Curve25519)
 /// - `secp256r1` (P-256, NIST Curve)
 /// - `secp384r1` (P-384, NIST Curve)
 ///

src/crypto/dtls_aead.rs

@@ -10,35 +10,37 @@ use crate::types::{ContentType, Sequence};
 /// Explicit nonce length for DTLS AEAD records.
 ///
 /// The explicit nonce is transmitted with each record.
+#[cfg(test)]
 pub(crate) const DTLS_EXPLICIT_NONCE_LEN: usize = 8;
 
 /// GCM authentication tag length.
 ///
 /// The tag is appended to the ciphertext.
+#[cfg(test)]
 pub(crate) const GCM_TAG_LEN: usize = 16;
 
-/// Overhead per AEAD record (explicit nonce + tag).
+/// Overhead per DTLS 1.2 AES-GCM record (explicit nonce + tag).
 ///
 /// This equals 24 bytes for DTLS AES-GCM.
+#[cfg(test)]
 pub(crate) const DTLS_AEAD_OVERHEAD: usize = DTLS_EXPLICIT_NONCE_LEN + GCM_TAG_LEN; // 24
 
-/// Compute AAD length from plaintext length for AEAD records.
-/// For DTLS AEAD this is the plaintext length.
+/// Compute AAD length from plaintext length for DTLS 1.2 AES-GCM records.
 #[inline]
 #[cfg(test)]
 pub fn aad_len_from_plaintext_len(plaintext_len: u16) -> u16 {
     plaintext_len
 }
 
-/// Compute fragment length from plaintext length for AEAD records.
+/// Compute fragment length from plaintext length for DTLS 1.2 AES-GCM records.
 /// fragment_len = explicit_nonce(8) + ciphertext(plaintext_len + 16 tag)
 #[inline]
 #[cfg(test)]
 pub fn fragment_len_from_plaintext_len(plaintext_len: usize) -> usize {
     DTLS_EXPLICIT_NONCE_LEN + plaintext_len + GCM_TAG_LEN
 }
 
-/// Compute plaintext length from fragment length, if large enough.
+/// Compute plaintext length from fragment length for DTLS 1.2 AES-GCM records.
 /// Returns None if the fragment is smaller than the mandatory AEAD overhead.
 #[inline]
 #[cfg(test)]
@@ -47,13 +49,51 @@ pub fn plaintext_len_from_fragment_len(fragment_len: usize) -> Option<usize> {
 }
 
 /// Fixed IV portion for DTLS AEAD.
+///
+/// DTLS 1.2 uses:
+/// - AES-GCM: 4-byte fixed IV + 8-byte explicit nonce (per record)
+/// - ChaCha20-Poly1305: 12-byte fixed IV + 0-byte explicit nonce
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub(crate) struct Iv(pub [u8; 4]);
+pub(crate) struct Iv {
+    bytes: [u8; 12],
+    len: u8,
+}
 
 impl Iv {
     pub(crate) fn new(iv: &[u8]) -> Self {
-        // invariant: the iv is 4 bytes.
-        Self(iv.try_into().unwrap())
+        assert!(
+            iv.len() <= 12,
+            "invalid IV length: expected <= 12, got {}",
+            iv.len()
+        );
+        let mut bytes = [0u8; 12];
+        bytes[..iv.len()].copy_from_slice(iv);
+        Self {
+            bytes,
+            len: iv.len() as u8,
+        }
+    }
+
+    pub(crate) fn len(&self) -> usize {
+        self.len as usize
+    }
+
+    pub(crate) fn as_slice(&self) -> &[u8] {
+        &self.bytes[..self.len()]
+    }
+
+    /// Returns the full 12-byte backing array.
+    ///
+    /// Only valid for 12-byte IVs (ChaCha20-Poly1305). For 4-byte IVs
+    /// (AES-GCM), use [`as_slice`] instead.
+    pub(crate) fn as_12_bytes(&self) -> &[u8; 12] {
+        debug_assert_eq!(
+            self.len(),
+            12,
+            "as_12_bytes called on {}-byte IV",
+            self.len()
+        );
+        &self.bytes
     }
 }
 
@@ -64,15 +104,25 @@ pub struct Nonce(pub [u8; 12]);
 impl Nonce {
     /// Create a new AEAD nonce by combining fixed IV and explicit nonce (DTLS 1.2).
     pub(crate) fn new(iv: Iv, explicit_nonce: &[u8]) -> Self {
+        assert_eq!(
+            iv.len() + explicit_nonce.len(),
+            12,
+            "invalid DTLS 1.2 nonce parts: iv_len={}, explicit_nonce_len={}",
+            iv.len(),
+            explicit_nonce.len()
+        );
         let mut nonce = [0u8; 12];
-        nonce[..4].copy_from_slice(&iv.0);
-        nonce[4..].copy_from_slice(explicit_nonce);
+        let iv_len = iv.len();
+        nonce[..iv_len].copy_from_slice(iv.as_slice());
+        nonce[iv_len..].copy_from_slice(explicit_nonce);
         Self(nonce)
     }
 
-    /// Create a DTLS 1.3 nonce by XORing the IV with the padded sequence number.
+    /// Create a nonce by XORing the IV with the padded sequence number.
     ///
-    /// Per RFC 8446 Section 5.3: nonce = iv XOR pad_left(seq, iv_len)
+    /// Used by both DTLS 1.2 (ChaCha20-Poly1305) and DTLS 1.3:
+    /// nonce = iv XOR pad_left(sequence_number, 12)
+    /// See RFC 8446 Section 5.3 / RFC 7905.
     pub(crate) fn xor(iv: &[u8; 12], seq: u64) -> Self {
         let mut nonce = *iv;
         let seq_bytes = seq.to_be_bytes(); // 8 bytes

src/crypto/mod.rs

@@ -22,7 +22,7 @@ pub use keying::{KeyingMaterial, SrtpProfile};
 pub use dtls_aead::{Aad, Nonce};
 
 // Re-export internal AEAD constants/types for crate-internal use
-pub(crate) use dtls_aead::{Iv, DTLS_AEAD_OVERHEAD, DTLS_EXPLICIT_NONCE_LEN};
+pub(crate) use dtls_aead::Iv;
 
 // Re-export buffer types for provider trait implementations
 pub use crate::buffer::{Buf, TmpBuf};

src/crypto/provider.rs

@@ -109,6 +109,14 @@
 //!         (0, 16, 4) // (mac_key_len, enc_key_len, fixed_iv_len)
 //!     }
 //!
+//!     fn explicit_nonce_len(&self) -> usize {
+//!         8 // AES-GCM: 8-byte explicit nonce per record
+//!     }
+//!
+//!     fn tag_len(&self) -> usize {
+//!         16 // 128-bit authentication tag
+//!     }
+//!
 //!     fn create_cipher(&self, key: &[u8]) -> Result<Box<dyn Cipher>, String> {
 //!         // Create your cipher implementation here
 //!         Ok(Box::new(MyCipher::new(key)?))
@@ -123,8 +131,8 @@
 //!
 //! For DTLS 1.2, implementations must support:
 //!
-//! - **Cipher suites**: ECDHE_ECDSA with AES-128-GCM or AES-256-GCM
-//! - **Key exchange**: ECDHE with P-256 or P-384 curves
+//! - **Cipher suites**: ECDHE_ECDSA with AES-128-GCM, AES-256-GCM, or CHACHA20_POLY1305
+//! - **Key exchange**: ECDHE with X25519, P-256, or P-384 curves
 //! - **Signatures**: ECDSA with P-256/SHA-256 or P-384/SHA-384
 //! - **Hash**: SHA-256 and SHA-384
 //! - **PRF**: TLS 1.2 PRF (using HMAC-SHA256 or HMAC-SHA384)
@@ -231,6 +239,14 @@ pub trait SupportedDtls12CipherSuite: CryptoSafe {
     /// Key material lengths: (mac_key_len, enc_key_len, fixed_iv_len).
     fn key_lengths(&self) -> (usize, usize, usize);
 
+    /// Length in bytes of the per-record explicit nonce (carried in the record body).
+    ///
+    /// AES-GCM suites carry an 8-byte explicit nonce; ChaCha20-Poly1305 carries none.
+    fn explicit_nonce_len(&self) -> usize;
+
+    /// AEAD authentication tag length in bytes.
+    fn tag_len(&self) -> usize;
+
     /// Create a cipher instance with the given key.
     fn create_cipher(&self, key: &[u8]) -> Result<Box<dyn Cipher>, String>;
 }