Add DTLS 1.3 record number encryption mask primitive for AES and ChaCha20 (RFC 9147 4.2.3), relates to github #1468.

Author: mondain

tls/src/main/java/org/bouncycastle/tls/crypto/impl/TlsRecordNumberMask.java

@@ -0,0 +1,25 @@
+package org.bouncycastle.tls.crypto.impl;
+
+import java.io.IOException;
+
+/**
+ * Record number encryption mask generator for DTLS 1.3 (RFC 9147 4.2.3).
+ * <p>
+ * The mask is derived from the first 16 bytes of the protected record using the block function underlying the
+ * negotiated AEAD (AES-ECB for AES-based AEADs, the ChaCha20 block function for ChaCha20-Poly1305), and is XORed
+ * with the sequence number bytes of the unified header.
+ * </p>
+ */
+public interface TlsRecordNumberMask
+{
+    /**
+     * Set the sequence number key ("sn" traffic key) for this direction.
+     */
+    void setKey(byte[] key, int keyOff, int keyLen) throws IOException;
+
+    /**
+     * Generate the 16-byte mask for a record whose ciphertext starts at 'ciphertextOff'. At least 16 bytes of
+     * ciphertext must be available. The mask is written to mask[maskOff..maskOff + 16).
+     */
+    void generateMask(byte[] ciphertext, int ciphertextOff, byte[] mask, int maskOff) throws IOException;
+}

tls/src/main/java/org/bouncycastle/tls/crypto/impl/bc/BcTlsAESRecordNumberMask.java

@@ -0,0 +1,47 @@
+package org.bouncycastle.tls.crypto.impl.bc;
+
+import java.io.IOException;
+
+import org.bouncycastle.crypto.BlockCipher;
+import org.bouncycastle.crypto.params.KeyParameter;
+import org.bouncycastle.tls.AlertDescription;
+import org.bouncycastle.tls.TlsFatalAlert;
+import org.bouncycastle.tls.crypto.impl.TlsRecordNumberMask;
+
+/**
+ * RFC 9147 4.2.3: Mask = AES-ECB(sn_key, Ciphertext[0..15]).
+ */
+public class BcTlsAESRecordNumberMask
+    implements TlsRecordNumberMask
+{
+    private final BlockCipher cipher;
+
+    public BcTlsAESRecordNumberMask(BlockCipher cipher)
+    {
+        this.cipher = cipher;
+    }
+
+    public void setKey(byte[] key, int keyOff, int keyLen) throws IOException
+    {
+        try
+        {
+            cipher.init(true, new KeyParameter(key, keyOff, keyLen));
+        }
+        catch (RuntimeException e)
+        {
+            throw new TlsFatalAlert(AlertDescription.internal_error, e);
+        }
+    }
+
+    public void generateMask(byte[] ciphertext, int ciphertextOff, byte[] mask, int maskOff) throws IOException
+    {
+        try
+        {
+            cipher.processBlock(ciphertext, ciphertextOff, mask, maskOff);
+        }
+        catch (RuntimeException e)
+        {
+            throw new TlsFatalAlert(AlertDescription.internal_error, e);
+        }
+    }
+}

tls/src/main/java/org/bouncycastle/tls/crypto/impl/bc/BcTlsChaCha20RecordNumberMask.java

@@ -0,0 +1,55 @@
+package org.bouncycastle.tls.crypto.impl.bc;
+
+import java.io.IOException;
+
+import org.bouncycastle.crypto.engines.ChaCha7539Engine;
+import org.bouncycastle.crypto.params.KeyParameter;
+import org.bouncycastle.crypto.params.ParametersWithIV;
+import org.bouncycastle.tls.AlertDescription;
+import org.bouncycastle.tls.TlsFatalAlert;
+import org.bouncycastle.tls.crypto.impl.TlsRecordNumberMask;
+import org.bouncycastle.util.Pack;
+
+/**
+ * RFC 9147 4.2.3: Mask = ChaCha20(sn_key, Ciphertext[0..3], Ciphertext[4..15]), i.e. the ChaCha20 block
+ * selected by the 32-bit little-endian counter in the first 4 ciphertext bytes and the 96-bit nonce in the
+ * following 12 bytes.
+ */
+public class BcTlsChaCha20RecordNumberMask
+    implements TlsRecordNumberMask
+{
+    private static final byte[] ZEROES = new byte[16];
+
+    private final ChaCha7539Engine cipher = new ChaCha7539Engine();
+
+    private KeyParameter key;
+
+    public void setKey(byte[] key, int keyOff, int keyLen) throws IOException
+    {
+        this.key = new KeyParameter(key, keyOff, keyLen);
+    }
+
+    public void generateMask(byte[] ciphertext, int ciphertextOff, byte[] mask, int maskOff) throws IOException
+    {
+        if (null == key)
+        {
+            throw new TlsFatalAlert(AlertDescription.internal_error);
+        }
+
+        try
+        {
+            long counter = Pack.littleEndianToInt(ciphertext, ciphertextOff) & 0xFFFFFFFFL;
+
+            byte[] nonce = new byte[12];
+            System.arraycopy(ciphertext, ciphertextOff + 4, nonce, 0, 12);
+
+            cipher.init(true, new ParametersWithIV(key, nonce));
+            cipher.skip(counter * 64L);
+            cipher.processBytes(ZEROES, 0, 16, mask, maskOff);
+        }
+        catch (RuntimeException e)
+        {
+            throw new TlsFatalAlert(AlertDescription.internal_error, e);
+        }
+    }
+}

tls/src/main/java/org/bouncycastle/tls/crypto/impl/jcajce/JceAESRecordNumberMask.java

@@ -0,0 +1,54 @@
+package org.bouncycastle.tls.crypto.impl.jcajce;
+
+import java.io.IOException;
+import java.security.GeneralSecurityException;
+
+import javax.crypto.Cipher;
+import javax.crypto.spec.SecretKeySpec;
+
+import org.bouncycastle.jcajce.util.JcaJceHelper;
+import org.bouncycastle.tls.AlertDescription;
+import org.bouncycastle.tls.TlsFatalAlert;
+import org.bouncycastle.tls.crypto.impl.TlsRecordNumberMask;
+
+/**
+ * RFC 9147 4.2.3: Mask = AES-ECB(sn_key, Ciphertext[0..15]), via a JCA "AES/ECB/NoPadding" cipher.
+ */
+public class JceAESRecordNumberMask
+    implements TlsRecordNumberMask
+{
+    private final Cipher cipher;
+
+    public JceAESRecordNumberMask(JcaJceHelper helper) throws GeneralSecurityException
+    {
+        this.cipher = helper.createCipher("AES/ECB/NoPadding");
+    }
+
+    public void setKey(byte[] key, int keyOff, int keyLen) throws IOException
+    {
+        try
+        {
+            cipher.init(Cipher.ENCRYPT_MODE, new SecretKeySpec(key, keyOff, keyLen, "AES"));
+        }
+        catch (GeneralSecurityException e)
+        {
+            throw new TlsFatalAlert(AlertDescription.internal_error, e);
+        }
+    }
+
+    public void generateMask(byte[] ciphertext, int ciphertextOff, byte[] mask, int maskOff) throws IOException
+    {
+        try
+        {
+            int len = cipher.doFinal(ciphertext, ciphertextOff, 16, mask, maskOff);
+            if (16 != len)
+            {
+                throw new TlsFatalAlert(AlertDescription.internal_error);
+            }
+        }
+        catch (GeneralSecurityException e)
+        {
+            throw new TlsFatalAlert(AlertDescription.internal_error, e);
+        }
+    }
+}

tls/src/main/java/org/bouncycastle/tls/crypto/impl/jcajce/JceChaCha20RecordNumberMask.java

@@ -0,0 +1,58 @@
+package org.bouncycastle.tls.crypto.impl.jcajce;
+
+import java.io.IOException;
+
+import org.bouncycastle.crypto.engines.ChaCha7539Engine;
+import org.bouncycastle.crypto.params.KeyParameter;
+import org.bouncycastle.crypto.params.ParametersWithIV;
+import org.bouncycastle.tls.AlertDescription;
+import org.bouncycastle.tls.TlsFatalAlert;
+import org.bouncycastle.tls.crypto.impl.TlsRecordNumberMask;
+import org.bouncycastle.util.Pack;
+
+/**
+ * RFC 9147 4.2.3: Mask = ChaCha20(sn_key, Ciphertext[0..3], Ciphertext[4..15]).
+ * <p>
+ * The JCA has no ChaCha20 cipher able to position the block counter on the Java versions this module targets
+ * (the base sources compile for Java 8 and below; {@code ChaCha20ParameterSpec}, which carries a counter, only
+ * arrived in Java 11), so the lightweight engine is used here, as {@link JcaNonceGenerator} does for its DRBG.
+ * </p>
+ */
+public class JceChaCha20RecordNumberMask
+    implements TlsRecordNumberMask
+{
+    private static final byte[] ZEROES = new byte[16];
+
+    private final ChaCha7539Engine cipher = new ChaCha7539Engine();
+
+    private KeyParameter key;
+
+    public void setKey(byte[] key, int keyOff, int keyLen) throws IOException
+    {
+        this.key = new KeyParameter(key, keyOff, keyLen);
+    }
+
+    public void generateMask(byte[] ciphertext, int ciphertextOff, byte[] mask, int maskOff) throws IOException
+    {
+        if (null == key)
+        {
+            throw new TlsFatalAlert(AlertDescription.internal_error);
+        }
+
+        try
+        {
+            long counter = Pack.littleEndianToInt(ciphertext, ciphertextOff) & 0xFFFFFFFFL;
+
+            byte[] nonce = new byte[12];
+            System.arraycopy(ciphertext, ciphertextOff + 4, nonce, 0, 12);
+
+            cipher.init(true, new ParametersWithIV(key, nonce));
+            cipher.skip(counter * 64L);
+            cipher.processBytes(ZEROES, 0, 16, mask, maskOff);
+        }
+        catch (RuntimeException e)
+        {
+            throw new TlsFatalAlert(AlertDescription.internal_error, e);
+        }
+    }
+}

tls/src/test/java/org/bouncycastle/tls/AllTests.java

@@ -24,6 +24,7 @@ public static Test suite()
         suite.addTestSuite(Add13CertificateStatusTest.class);
         suite.addTestSuite(CheckTlsFeaturesExtensionTest.class);
         suite.addTestSuite(DTLSReassemblerTest.class);
+        suite.addTestSuite(DTLSRecordNumberMaskTest.class);
         suite.addTestSuite(SpreadCertificateStatusTest.class);
 
         return new BCTestSetup(suite);

tls/src/test/java/org/bouncycastle/tls/DTLSRecordNumberMaskTest.java

@@ -0,0 +1,108 @@
+package org.bouncycastle.tls;
+
+import java.security.SecureRandom;
+
+import org.bouncycastle.crypto.engines.AESEngine;
+import org.bouncycastle.crypto.engines.ChaCha7539Engine;
+import org.bouncycastle.crypto.params.KeyParameter;
+import org.bouncycastle.crypto.params.ParametersWithIV;
+import org.bouncycastle.jcajce.util.DefaultJcaJceHelper;
+import org.bouncycastle.tls.crypto.impl.TlsRecordNumberMask;
+import org.bouncycastle.tls.crypto.impl.bc.BcTlsAESRecordNumberMask;
+import org.bouncycastle.tls.crypto.impl.bc.BcTlsChaCha20RecordNumberMask;
+import org.bouncycastle.tls.crypto.impl.jcajce.JceAESRecordNumberMask;
+import org.bouncycastle.tls.crypto.impl.jcajce.JceChaCha20RecordNumberMask;
+import org.bouncycastle.util.Arrays;
+
+import junit.framework.TestCase;
+
+/**
+ * RFC 9147 4.2.3 record number encryption masks: AES-ECB over the first 16 ciphertext bytes, or the ChaCha20
+ * block selected by the first 4 ciphertext bytes (counter) and the next 12 (nonce). Both backends must agree
+ * with an independent lightweight reference.
+ */
+public class DTLSRecordNumberMaskTest
+    extends TestCase
+{
+    private static final SecureRandom RANDOM = new SecureRandom();
+
+    public void testAESMaskMatchesECBReference() throws Exception
+    {
+        byte[] key = new byte[16];
+        byte[] ciphertext = new byte[40];
+        RANDOM.nextBytes(key);
+        RANDOM.nextBytes(ciphertext);
+
+        AESEngine reference = new AESEngine();
+        reference.init(true, new KeyParameter(key));
+        byte[] expected = new byte[16];
+        reference.processBlock(ciphertext, 8, expected, 0);
+
+        TlsRecordNumberMask bc = new BcTlsAESRecordNumberMask(new AESEngine());
+        bc.setKey(key, 0, key.length);
+        byte[] actualBc = new byte[16];
+        bc.generateMask(ciphertext, 8, actualBc, 0);
+        assertTrue(Arrays.areEqual(expected, actualBc));
+
+        TlsRecordNumberMask jce = new JceAESRecordNumberMask(new DefaultJcaJceHelper());
+        jce.setKey(key, 0, key.length);
+        byte[] actualJce = new byte[16];
+        jce.generateMask(ciphertext, 8, actualJce, 0);
+        assertTrue(Arrays.areEqual(expected, actualJce));
+    }
+
+    public void testChaCha20MaskMatchesKeystreamReference() throws Exception
+    {
+        byte[] key = new byte[32];
+        byte[] ciphertext = new byte[32];
+        RANDOM.nextBytes(key);
+        RANDOM.nextBytes(ciphertext);
+
+        // counter = 3 (little-endian), so the mask is keystream bytes [192, 208)
+        ciphertext[0] = 3;
+        ciphertext[1] = 0;
+        ciphertext[2] = 0;
+        ciphertext[3] = 0;
+
+        byte[] nonce = Arrays.copyOfRange(ciphertext, 4, 16);
+        ChaCha7539Engine reference = new ChaCha7539Engine();
+        reference.init(true, new ParametersWithIV(new KeyParameter(key), nonce));
+        byte[] stream = new byte[3 * 64 + 16];
+        reference.processBytes(stream, 0, stream.length, stream, 0);
+        byte[] expected = Arrays.copyOfRange(stream, 192, 208);
+
+        TlsRecordNumberMask bc = new BcTlsChaCha20RecordNumberMask();
+        bc.setKey(key, 0, key.length);
+        byte[] actualBc = new byte[16];
+        bc.generateMask(ciphertext, 0, actualBc, 0);
+        assertTrue(Arrays.areEqual(expected, actualBc));
+
+        TlsRecordNumberMask jce = new JceChaCha20RecordNumberMask();
+        jce.setKey(key, 0, key.length);
+        byte[] actualJce = new byte[16];
+        jce.generateMask(ciphertext, 0, actualJce, 0);
+        assertTrue(Arrays.areEqual(expected, actualJce));
+    }
+
+    public void testChaCha20MaskLargeCounter() throws Exception
+    {
+        byte[] key = new byte[32];
+        byte[] ciphertext = new byte[16];
+        RANDOM.nextBytes(key);
+        RANDOM.nextBytes(ciphertext);
+        ciphertext[3] = (byte)0xFF; // counter near 2^32
+
+        TlsRecordNumberMask bc = new BcTlsChaCha20RecordNumberMask();
+        bc.setKey(key, 0, key.length);
+        byte[] a = new byte[16];
+        bc.generateMask(ciphertext, 0, a, 0);
+
+        TlsRecordNumberMask jce = new JceChaCha20RecordNumberMask();
+        jce.setKey(key, 0, key.length);
+        byte[] b = new byte[16];
+        jce.generateMask(ciphertext, 0, b, 0);
+
+        assertTrue(Arrays.areEqual(a, b));
+        assertFalse(Arrays.areEqual(new byte[16], a));
+    }
+}