Use the "dtls13" HKDF-Expand-Label prefix for the DTLS 1.3 key schedule (RFC 9147 section 5.9) instead of TLS 1.3's "tls13 ", so DTLS 1.3 traffic keys, record number keys, Finished keys and exporters interoperate with other implementations, relates to github #1468.

Author: JonathanLennox

tls/src/main/java/org/bouncycastle/tls/AbstractTlsContext.java

@@ -289,8 +289,9 @@ else if (!TlsUtils.isValidUint16(context.length))
             TlsHash exporterHash = getCrypto().createHash(cryptoHashAlgorithm);
             byte[] emptyTranscriptHash = exporterHash.calculateHash();
 
-            TlsSecret exporterSecret = TlsUtils.deriveSecret(getSecurityParametersConnection(), secret, asciiLabel,
-                emptyTranscriptHash);
+            SecurityParameters sp = getSecurityParametersConnection();
+
+            TlsSecret exporterSecret = TlsUtils.deriveSecret(sp, secret, asciiLabel, emptyTranscriptHash);
 
             byte[] exporterContext = emptyTranscriptHash;
             if (context.length > 0)
@@ -299,8 +300,12 @@ else if (!TlsUtils.isValidUint16(context.length))
                 exporterContext = exporterHash.calculateHash();
             }
 
+            // RFC 9147 5.9. DTLS 1.3 derives with the "dtls13" label prefix rather than TLS 1.3's "tls13 ".
+            boolean isDTLS = sp.getNegotiatedVersion().isDTLS();
+
             return TlsCryptoUtils
-                .hkdfExpandLabel(exporterSecret, cryptoHashAlgorithm, "exporter", exporterContext, length).extract();
+                .hkdfExpandLabel(exporterSecret, cryptoHashAlgorithm, "exporter", exporterContext, length, isDTLS)
+                .extract();
         }
         catch (IOException e)
         {

tls/src/main/java/org/bouncycastle/tls/OfferedPsks.java

@@ -144,8 +144,12 @@ public void encode(OutputStream output) throws IOException
         }
     }
 
+    /**
+     * @param isDTLS whether the binders are for a DTLS 1.3 ClientHello, which selects the "dtls13" HKDF label prefix
+     *               (RFC 9147 5.9) rather than TLS 1.3's "tls13 ".
+     */
     static void encodeBinders(OutputStream output, TlsCrypto crypto, TlsHandshakeHash handshakeHash,
-        BindersConfig bindersConfig) throws IOException
+        BindersConfig bindersConfig, boolean isDTLS) throws IOException
     {
         TlsPSK[] psks = bindersConfig.psks;
         TlsSecret[] earlySecrets = bindersConfig.earlySecrets;
@@ -170,7 +174,7 @@ static void encodeBinders(OutputStream output, TlsCrypto crypto, TlsHandshakeHas
             byte[] transcriptHash = hash.calculateHash();
 
             byte[] binder = TlsUtils.calculatePSKBinder(crypto, isExternalPSK, pskCryptoHashAlgorithm, earlySecret,
-                transcriptHash);
+                transcriptHash, isDTLS);
 
             lengthOfBindersList += 1 + binder.length;
             TlsUtils.writeOpaque8(binder, output);

tls/src/main/java/org/bouncycastle/tls/TlsClientProtocol.java

@@ -2008,7 +2008,8 @@ protected void sendClientHelloMessage() throws IOException
 
         if (null != clientBinders)
         {
-            OfferedPsks.encodeBinders(message, tlsClientContext.getCrypto(), handshakeHash, clientBinders);
+            // TLS over TCP, so the binders use the TLS 1.3 label prefix
+            OfferedPsks.encodeBinders(message, tlsClientContext.getCrypto(), handshakeHash, clientBinders, false);
         }
 
         message.sendClientHello(this, handshakeHash, clientHello.getBindersSize());

tls/src/main/java/org/bouncycastle/tls/TlsUtils.java

@@ -1776,15 +1776,16 @@ private static byte[] calculateFinishedHMAC(SecurityParameters securityParameter
     {
         int prfCryptoHashAlgorithm = securityParameters.getPRFCryptoHashAlgorithm();
         int prfHashLength = securityParameters.getPRFHashLength(); 
+        boolean isDTLS = isDTLS(securityParameters);
 
-        return calculateFinishedHMAC(prfCryptoHashAlgorithm, prfHashLength, baseKey, transcriptHash);
+        return calculateFinishedHMAC(prfCryptoHashAlgorithm, prfHashLength, baseKey, transcriptHash, isDTLS);
     }
 
     private static byte[] calculateFinishedHMAC(int prfCryptoHashAlgorithm, int prfHashLength, TlsSecret baseKey,
-        byte[] transcriptHash) throws IOException
+        byte[] transcriptHash, boolean isDTLS) throws IOException
     {
         TlsSecret finishedKey = TlsCryptoUtils.hkdfExpandLabel(baseKey, prfCryptoHashAlgorithm, "finished", EMPTY_BYTES,
-            prfHashLength);
+            prfHashLength, isDTLS);
 
         try
         {
@@ -1817,19 +1818,19 @@ static TlsSecret calculateMasterSecret(TlsContext context, TlsSecret preMasterSe
     }
 
     static byte[] calculatePSKBinder(TlsCrypto crypto, boolean isExternalPSK, int pskCryptoHashAlgorithm,
-        TlsSecret earlySecret, byte[] transcriptHash) throws IOException
+        TlsSecret earlySecret, byte[] transcriptHash, boolean isDTLS) throws IOException
     {
         int prfHashLength = TlsCryptoUtils.getHashOutputSize(pskCryptoHashAlgorithm);
 
         String label = isExternalPSK ? "ext binder" : "res binder";
         byte[] emptyTranscriptHash = crypto.createHash(pskCryptoHashAlgorithm).calculateHash();
 
         TlsSecret binderKey = deriveSecret(pskCryptoHashAlgorithm, prfHashLength, earlySecret, label,
-            emptyTranscriptHash);
+            emptyTranscriptHash, isDTLS);
 
         try
         {
-            return calculateFinishedHMAC(pskCryptoHashAlgorithm, prfHashLength, binderKey, transcriptHash);
+            return calculateFinishedHMAC(pskCryptoHashAlgorithm, prfHashLength, binderKey, transcriptHash, isDTLS);
         }
         finally
         {
@@ -2012,7 +2013,21 @@ private static void update13TrafficSecret(TlsContext context, boolean forServer)
     private static TlsSecret update13TrafficSecret(SecurityParameters securityParameters, TlsSecret secret) throws IOException
     {
         return TlsCryptoUtils.hkdfExpandLabel(secret, securityParameters.getPRFCryptoHashAlgorithm(), "traffic upd",
-            EMPTY_BYTES, securityParameters.getPRFHashLength());
+            EMPTY_BYTES, securityParameters.getPRFHashLength(), isDTLS(securityParameters));
+    }
+
+    /**
+     * Whether the (D)TLS 1.3 key schedule for these security parameters uses the DTLS 1.3 label prefix (RFC 9147
+     * 5.9), i.e. whether the negotiated version is a DTLS version.
+     */
+    private static boolean isDTLS(SecurityParameters securityParameters)
+    {
+        ProtocolVersion negotiatedVersion = securityParameters.getNegotiatedVersion();
+        if (null == negotiatedVersion)
+        {
+            throw new IllegalStateException("(D)TLS 1.3 key derivation before the version is negotiated");
+        }
+        return negotiatedVersion.isDTLS();
     }
 
     public static ASN1ObjectIdentifier getOIDForHashAlgorithm(short hashAlgorithm)
@@ -6117,18 +6132,20 @@ static TlsSecret deriveSecret(SecurityParameters securityParameters, TlsSecret s
         int prfCryptoHashAlgorithm = securityParameters.getPRFCryptoHashAlgorithm();
         int prfHashLength = securityParameters.getPRFHashLength();
 
-        return deriveSecret(prfCryptoHashAlgorithm, prfHashLength, secret, label, transcriptHash);
+        return deriveSecret(prfCryptoHashAlgorithm, prfHashLength, secret, label, transcriptHash,
+            isDTLS(securityParameters));
     }
 
     static TlsSecret deriveSecret(int prfCryptoHashAlgorithm, int prfHashLength, TlsSecret secret, String label,
-        byte[] transcriptHash) throws IOException
+        byte[] transcriptHash, boolean isDTLS) throws IOException
     {
         if (transcriptHash.length != prfHashLength)
         {
             throw new TlsFatalAlert(AlertDescription.internal_error);
         }
 
-        return TlsCryptoUtils.hkdfExpandLabel(secret, prfCryptoHashAlgorithm, label, transcriptHash, prfHashLength);
+        return TlsCryptoUtils.hkdfExpandLabel(secret, prfCryptoHashAlgorithm, label, transcriptHash, prfHashLength,
+            isDTLS);
     }
 
     static TlsSecret getSessionMasterSecret(TlsCrypto crypto, TlsSecret masterSecret)
@@ -6449,7 +6466,7 @@ static OfferedPsks.SelectedConfig selectPreSharedKey(TlsServerContext serverCont
                         }
 
                         byte[] calculatedBinder = calculatePSKBinder(crypto, isExternalPSK, pskCryptoHashAlgorithm,
-                            earlySecret, transcriptHash);
+                            earlySecret, transcriptHash, serverContext.getServerVersion().isDTLS());
 
                         if (!Arrays.constantTimeAreEqual(calculatedBinder, binder))
                         {

tls/src/main/java/org/bouncycastle/tls/crypto/TlsCryptoUtils.java

@@ -21,6 +21,9 @@ public abstract class TlsCryptoUtils
     // "tls13 "
     private static final byte[] TLS13_PREFIX = new byte[]{ 0x74, 0x6c, 0x73, 0x31, 0x33, 0x20 };
 
+    // "dtls13" (RFC 9147 5.9: no trailing space, so that the expanded label stays within one hash block)
+    private static final byte[] DTLS13_PREFIX = new byte[]{ 0x64, 0x74, 0x6c, 0x73, 0x31, 0x33 };
+
     public static int getHash(short hashAlgorithm)
     {
         switch (hashAlgorithm)
@@ -192,17 +195,36 @@ public static int getSignature(short signatureAlgorithm)
         }
     }
 
+    /**
+     * HKDF-Expand-Label as defined in RFC 8446 7.1, with the "tls13 " label prefix. This is the TLS 1.3 form; for
+     * DTLS 1.3 use {@link #hkdfExpandLabel(TlsSecret, int, String, byte[], int, boolean)}, since RFC 9147 5.9
+     * requires the "dtls13" prefix there.
+     */
     public static TlsSecret hkdfExpandLabel(TlsSecret secret, int cryptoHashAlgorithm, String label, byte[] context,
         int length) throws IOException
+    {
+        return hkdfExpandLabel(secret, cryptoHashAlgorithm, label, context, length, false);
+    }
+
+    /**
+     * HKDF-Expand-Label as defined in RFC 8446 7.1, with the label prefix selected by the protocol: "tls13 " for
+     * TLS 1.3, or "dtls13" for DTLS 1.3 (RFC 9147 5.9, which requires this for key separation between the two).
+     *
+     * @param isDTLS true to use the DTLS 1.3 label prefix, false for the TLS 1.3 one.
+     */
+    public static TlsSecret hkdfExpandLabel(TlsSecret secret, int cryptoHashAlgorithm, String label, byte[] context,
+        int length, boolean isDTLS) throws IOException
     {
         int labelLength = label.length();
         if (labelLength < 1)
         {
             throw new TlsFatalAlert(AlertDescription.internal_error);
         }
 
+        byte[] prefix = isDTLS ? DTLS13_PREFIX : TLS13_PREFIX;
+
         int contextLength = context.length;
-        int expandedLabelLength = TLS13_PREFIX.length + labelLength;
+        int expandedLabelLength = prefix.length + labelLength;
 
         byte[] hkdfLabel = new byte[2 + (1 + expandedLabelLength) + (1 + contextLength)];
 
@@ -217,9 +239,9 @@ public static TlsSecret hkdfExpandLabel(TlsSecret secret, int cryptoHashAlgorith
             TlsUtils.checkUint8(expandedLabelLength);
             TlsUtils.writeUint8(expandedLabelLength, hkdfLabel, 2);
 
-            System.arraycopy(TLS13_PREFIX, 0, hkdfLabel, 2 + 1, TLS13_PREFIX.length);
+            System.arraycopy(prefix, 0, hkdfLabel, 2 + 1, prefix.length);
 
-            int labelPos = 2 + (1 + TLS13_PREFIX.length);
+            int labelPos = 2 + (1 + prefix.length);
             for (int i = 0; i < labelLength; ++i)
             {
                 char c = label.charAt(i);

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

@@ -205,15 +205,18 @@ private void rekeyHmac(SecurityParameters securityParameters, TlsHMAC hmac, byte
             throw new TlsFatalAlert(AlertDescription.internal_error);
         }
 
-        setupHmac(hmac, nonce, secret, securityParameters.getPRFCryptoHashAlgorithm());
+        // RFC 9147 5.9. DTLS 1.3 derives with the "dtls13" label prefix rather than TLS 1.3's "tls13 ".
+        boolean isDTLS = securityParameters.getNegotiatedVersion().isDTLS();
+
+        setupHmac(hmac, nonce, secret, securityParameters.getPRFCryptoHashAlgorithm(), isDTLS);
     }
 
-    private void setupHmac(TlsHMAC hmac, byte[] nonce, TlsSecret secret, int cryptoHashAlgorithm)
+    private void setupHmac(TlsHMAC hmac, byte[] nonce, TlsSecret secret, int cryptoHashAlgorithm, boolean isDTLS)
         throws IOException
     {
         int length = hmac.getMacLength();
-        byte[] key = hkdfExpandLabel(secret, cryptoHashAlgorithm, "key", length).extract();
-        byte[] iv = hkdfExpandLabel(secret, cryptoHashAlgorithm, "iv", length).extract();
+        byte[] key = hkdfExpandLabel(secret, cryptoHashAlgorithm, "key", length, isDTLS).extract();
+        byte[] iv = hkdfExpandLabel(secret, cryptoHashAlgorithm, "iv", length, isDTLS).extract();
 
         hmac.setKey(key, 0, length);
         System.arraycopy(iv, 0, nonce, 0, length);
@@ -241,9 +244,10 @@ private static byte[] getAdditionalData(long seqNo, short recordType, ProtocolVe
         return additional_data;
     }
 
-    private static TlsSecret hkdfExpandLabel(TlsSecret secret, int cryptoHashAlgorithm, String label, int length)
-        throws IOException
+    private static TlsSecret hkdfExpandLabel(TlsSecret secret, int cryptoHashAlgorithm, String label, int length,
+        boolean isDTLS) throws IOException
     {
-        return TlsCryptoUtils.hkdfExpandLabel(secret, cryptoHashAlgorithm, label, TlsUtils.EMPTY_BYTES, length);
+        return TlsCryptoUtils.hkdfExpandLabel(secret, cryptoHashAlgorithm, label, TlsUtils.EMPTY_BYTES, length,
+            isDTLS);
     }
 }

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

@@ -671,8 +671,9 @@ private void rekeyCipher(SecurityParameters securityParameters, TlsAEADCipherImp
     private void setup13Cipher(TlsAEADCipherImpl cipher, byte[] nonce, TlsRecordNumberMask mask, TlsSecret secret,
         int cryptoHashAlgorithm) throws IOException
     {
-        byte[] key = hkdfExpandLabel(secret, cryptoHashAlgorithm, "key", keySize).extract();
-        byte[] iv = hkdfExpandLabel(secret, cryptoHashAlgorithm, "iv", fixed_iv_length).extract();
+        // RFC 9147 5.9. DTLS 1.3 derives with the "dtls13" label prefix rather than TLS 1.3's "tls13 ".
+        byte[] key = hkdfExpandLabel(secret, cryptoHashAlgorithm, "key", keySize, isDTLSv13).extract();
+        byte[] iv = hkdfExpandLabel(secret, cryptoHashAlgorithm, "iv", fixed_iv_length, isDTLSv13).extract();
 
         cipher.setKey(key, 0, keySize);
         System.arraycopy(iv, 0, nonce, 0, fixed_iv_length);
@@ -687,7 +688,7 @@ private void setup13Cipher(TlsAEADCipherImpl cipher, byte[] nonce, TlsRecordNumb
                 throw new TlsFatalAlert(AlertDescription.internal_error, "No record number mask for DTLS 1.3");
             }
 
-            byte[] snKey = hkdfExpandLabel(secret, cryptoHashAlgorithm, "sn", keySize).extract();
+            byte[] snKey = hkdfExpandLabel(secret, cryptoHashAlgorithm, "sn", keySize, true).extract();
             mask.setKey(snKey, 0, keySize);
         }
     }
@@ -708,9 +709,10 @@ private static int getNonceMode(boolean isTLSv13, int aeadType) throws IOExcepti
         }
     }
 
-    private static TlsSecret hkdfExpandLabel(TlsSecret secret, int cryptoHashAlgorithm, String label, int length)
-        throws IOException
+    private static TlsSecret hkdfExpandLabel(TlsSecret secret, int cryptoHashAlgorithm, String label, int length,
+        boolean isDTLS) throws IOException
     {
-        return TlsCryptoUtils.hkdfExpandLabel(secret, cryptoHashAlgorithm, label, TlsUtils.EMPTY_BYTES, length);
+        return TlsCryptoUtils.hkdfExpandLabel(secret, cryptoHashAlgorithm, label, TlsUtils.EMPTY_BYTES, length,
+            isDTLS);
     }
 }

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

@@ -23,6 +23,7 @@ public static Test suite()
         suite.addTestSuite(AbstractTlsServerResetTest.class);
         suite.addTestSuite(Add13CertificateStatusTest.class);
         suite.addTestSuite(CheckTlsFeaturesExtensionTest.class);
+        suite.addTestSuite(DTLS13KeyScheduleLabelTest.class);
         suite.addTestSuite(DTLS13UnifiedHeaderTest.class);
         suite.addTestSuite(DTLSReassemblerTest.class);
         suite.addTestSuite(DTLSRecordLayer13Test.class);