lemon-tls 0.5.5 → 0.7.0

package/src/dtls_session.js

@@ -44,13 +44,17 @@ import {
 
 import {
   TLS_CIPHER_SUITES,
+  default_cipher_suites,
   hkdf_expand_label,
   derive_sn_key,
+  LABEL_PREFIX_TLS13,
+  LABEL_PREFIX_DTLS13,
 } from './crypto.js';
 
 import {
   CT,
   getAeadAlgo,
+  deriveKeys,
   deriveKeys12,
   decryptDtls12,
   buildDtlsPlaintext,
@@ -59,9 +63,12 @@ import {
   parseDtlsDatagram,
   buildDtlsAck,
   parseDtlsAck,
+  decryptEncryptedDtls13,
 } from './record.js';
 
 import { timingSafeEqualU8 } from './utils.js';
+import { SUPPORTED_GROUPS as ECDH_SUPPORTED_GROUPS } from './session/ecdh.js';
+import { default_signature_schemes } from './session/signing.js';
 
 
 // ============================================================
@@ -121,6 +128,48 @@ function _ldbg() {
   }
 }
 
+/**
+ * Log an OUTBOUND record. The existing _ldbg traces only what arrives —
+ * which is half the picture when a peer rejects something WE sent, and
+ * that is precisely the DTLS 1.3 interop case: BoringSSL reads our
+ * flight, dislikes it, and closes. Decoding the record header here
+ * (content type, epoch, sequence, and the handshake message type when
+ * the record is still in the clear) shows exactly what left the socket.
+ */
+function _ldbgTx(record, whereFrom) {
+  if (!LEMON_DEBUG || !record || !record.length) return;
+  try {
+    var ct = record[0];
+    // DTLS 1.3 UNIFIED HEADER (RFC 9147 4.1): an encrypted record starts
+    // with 001CSLEE — first byte in 0x20..0x3F — instead of the classic
+    // content-type/version/epoch/sequence header. Its epoch is the low
+    // two bits and the body is ciphertext, so all we can honestly report
+    // is that one went out and how big it was. Reading it as a classic
+    // header produced nonsense like "ct46 epoch=323".
+    if (ct >= 0x20 && ct <= 0x3F) {
+      _ldbg('TX [1.3 encrypted] epoch=' + (ct & 0x03) + ' len=' + record.length +
+            (whereFrom ? ' <' + whereFrom + '>' : ''));
+      return;
+    }
+    var epoch = (record[3] << 8) | record[4];
+    var names = { 20: 'ChangeCipherSpec', 21: 'Alert', 22: 'Handshake',
+                  23: 'ApplicationData', 25: 'Heartbeat', 26: 'ACK' };
+    var hsNames = { 1:'ClientHello', 2:'ServerHello', 4:'NewSessionTicket',
+                    8:'EncryptedExtensions', 11:'Certificate',
+                    13:'CertificateRequest', 15:'CertificateVerify',
+                    20:'Finished', 24:'KeyUpdate' };
+    var extra = '';
+    if (ct === 22 && record.length > 13) {
+      extra = ' hs=' + (hsNames[record[13]] || ('type' + record[13]));
+    }
+    if (ct === 21 && record.length >= 15) {
+      extra = ' alert level=' + record[13] + ' desc=' + record[14];
+    }
+    _ldbg('TX ' + (names[ct] || ('ct' + ct)) + ' epoch=' + epoch +
+          ' len=' + record.length + extra + (whereFrom ? ' <' + whereFrom + '>' : ''));
+  } catch (e) {}
+}
+
 function DTLSSession(options) {
   if (!(this instanceof DTLSSession)) return new DTLSSession(options);
   options = options || {};
@@ -141,6 +190,7 @@ function DTLSSession(options) {
     // byte and never the body, so any non-empty sid shears its whole
     // ClientHello parse.)
     sessionId: new Uint8Array(0),
+    srtpProfiles: options.srtpProfiles,
     servername: options.servername,
     SNICallback: options.SNICallback,
     rejectUnauthorized: options.rejectUnauthorized,
@@ -194,8 +244,22 @@ function DTLSSession(options) {
     // keyed by msg_seq, and drained in order once the gap is filled.
     pendingMessages: {},   // msg_seq → { type, body }
 
-    // Flight tracking for retransmission
-    currentFlight: [],     // array of { epoch, data: Uint8Array (complete datagram) }
+    // Flight tracking for retransmission.
+    //
+    // Stores PRE-ENCRYPTION descriptors — { epoch, contentType, payload } —
+    // never built records. Rebuilding at retransmit time (resendFlight) gives
+    // every retransmitted record a FRESH record sequence number, which is not
+    // an optimization but a hard requirement on two independent grounds:
+    //   1. DTLS 1.3 (RFC 9147 §4.2.1): the AEAD nonce is derived from the
+    //      record seq. Re-emitting a stored ciphertext repeats (key, nonce) —
+    //      catastrophic for GCM (key-stream reuse reveals plaintext XOR and
+    //      enables tag forgery). The old code stored fully-built records and
+    //      replayed the exact bytes.
+    //   2. Receivers reconstruct the full seq from its truncated wire form
+    //      relative to the highest seq seen (and BoGo outright requires
+    //      monotonic seqs from the shim) — a replayed old seq reconstructs to
+    //      a wrong full value and fails deprotection as "bad record MAC".
+    currentFlight: [],     // array of { epoch, contentType, payload: Uint8Array }
     // RFC 6347 §4.2.4 flight discipline: a NEW flight begins with the first
     // record we send after having accepted new handshake data from the peer.
     // Set when inbound processing advances state; consumed (and reset) by
@@ -206,6 +270,23 @@ function DTLSSession(options) {
     // too — which a connected werift server answers with renegotiation(),
     // destroying the session instead of recovering it.
     newFlightPending: false,
+
+    // ---- Epoch tracking (RFC 9147 §6.1) ----
+    // Sending and receiving epochs advance INDEPENDENTLY: a KeyUpdate rekeys
+    // one direction only. Until KeyUpdate existed both directions moved
+    // together through 0 -> 2 -> 3, so a single number sufficed; it does not
+    // any more. ctx.keys[e] therefore holds .write and .read for possibly
+    // different generations, and each half is installed on its own.
+    writeEpoch: null,          // epoch we currently PROTECT outgoing records with
+    readEpoch: null,           // highest epoch we hold READ keys for
+    // A KeyUpdate we have sent whose ACK has not come back. RFC 9147 §8:
+    // "implementations MUST NOT send records with the new keys or send a new
+    // KeyUpdate until the previous KeyUpdate has been acknowledged". So the
+    // new write keys are installed immediately but stay dormant here until
+    // the ACK arrives.
+    pendingWriteEpoch: null,
+    keyUpdateFlight: null,     // { payload, epoch, timer, attempts, timeout }
+
     retransmitTimer: null,
     retransmitCount: 0,
     retransmitTimeout: 1000,
@@ -253,24 +334,17 @@ function DTLSSession(options) {
   // Server defaults — TLSSession client auto-populates these, but server expects them set externally
   if (isServer) {
     if (!tlsSetup.local_supported_cipher_suites) {
-      let ciphers = [];
-      if (versions.indexOf(DTLS_VERSION.DTLS1_3) >= 0) {
-        ciphers.push(0x1301, 0x1302, 0x1303); // TLS 1.3 AEAD ciphers
-      }
-      if (versions.indexOf(DTLS_VERSION.DTLS1_2) >= 0) {
-        ciphers.push(0xC02F, 0xC030, 0xC02B, 0xC02C); // TLS 1.2 ECDHE ciphers
-      }
-      tlsSetup.local_supported_cipher_suites = ciphers;
+      // crypto.js owns the default suite list (see default_cipher_suites).
+      tlsSetup.local_supported_cipher_suites = default_cipher_suites(
+        versions.indexOf(DTLS_VERSION.DTLS1_3) >= 0,
+        versions.indexOf(DTLS_VERSION.DTLS1_2) >= 0
+      );
     }
     if (!tlsSetup.local_supported_groups) {
-      tlsSetup.local_supported_groups = [0x001d, 0x0017, 0x0018];
+      tlsSetup.local_supported_groups = ECDH_SUPPORTED_GROUPS.slice(); // whatever ecdh.js implements
     }
-    tlsSetup.local_supported_signature_algorithms = [
-      0x0804, 0x0805, 0x0806,  // RSA-PSS
-      0x0403, 0x0503, 0x0603,  // ECDSA
-      0x0807, 0x0808,          // EdDSA
-      0x0401, 0x0501, 0x0601,  // PKCS#1
-    ];
+    // signing.js owns the scheme list; DTLS spans 1.2+1.3 so include PKCS#1.
+    tlsSetup.local_supported_signature_algorithms = default_signature_schemes();
   }
 
   // Server cert/key
@@ -308,55 +382,151 @@ function DTLSSession(options) {
     }
     transcriptMsgSeqs.push(msgSeq);
 
-    if (ctx.selectedVersion === DTLS_VERSION.DTLS1_2) {
-      return build_dtls_handshake(data, msgSeq);
-    }
-    return data; // TLS format for DTLS 1.3 or unknown version
+    // RFC 9147 §5.9, verbatim: "Hash calculations include entire handshake
+    // messages, including DTLS-specific fields: message_seq,
+    // fragment_offset, and fragment_length. However, in order to remove
+    // sensitivity to handshake message fragmentation, the CertificateVerify
+    // and Finished messages MUST be computed as if each handshake message
+    // had been sent as a single fragment."
+    //
+    // So DTLS 1.3 keeps the 12-byte DTLS header in the transcript, exactly
+    // like DTLS 1.2 (RFC 6347 §4.2.6) — with fragment_offset 0 and
+    // fragment_length equal to the whole body, which is what
+    // build_dtls_handshake produces by default.
+    //
+    // This code did the OPPOSITE for 1.3 and stored TLS-format messages,
+    // citing a section number that says the reverse of what it does. The
+    // effect is invisible between two copies of this library — both make
+    // the same choice and their MACs agree — and only shows up against a
+    // conforming peer, where every message parses cleanly and then the
+    // Finished MAC fails: "Finished verify_data mismatch" against Chrome,
+    // with a transcript whose entries were each 8 bytes short.
+    // MEASURED AGAINST CHROME, and it contradicts the plain reading of
+    // RFC 9147 §5.9 ("Hash calculations include entire handshake
+    // messages, including DTLS-specific fields"):
+    //   • TLS-format transcript  -> Chrome's CertificateVerify VERIFIES,
+    //                               Finished MAC mismatches;
+    //   • DTLS-format transcript -> Chrome's CertificateVerify FAILS.
+    // So BoringSSL signs CertificateVerify over the TLS-format transcript.
+    // Since CertificateVerify is the one we can check against a real peer
+    // and it passes this way, TLS format stays for 1.3 — the Finished
+    // difference is something else and must be found without breaking a
+    // signature that demonstrably verifies.
+    let entry = (ctx.selectedVersion === DTLS_VERSION.DTLS1_2)
+      ? build_dtls_handshake(data, msgSeq)
+      : data;
+
+
+    return entry;
   };
 
   /**
    * Called when selectedVersion is first determined as DTLS 1.2.
    * Retroactively converts all existing transcript entries to DTLS format.
    */
-  function fixTranscriptForDtls12() {
+  /**
+   * Convert transcript entries recorded BEFORE the version was known into
+   * DTLS handshake format.
+   *
+   * Both DTLS 1.2 (RFC 6347 §4.2.6) and DTLS 1.3 (RFC 9147 §5.9) hash the
+   * 12-byte DTLS handshake header, but the first messages — our ClientHello
+   * and the peer's ServerHello — are pushed while selectedVersion is still
+   * null, so they land in TLS format and have to be rewritten once the
+   * negotiation resolves. Entries already in DTLS format are left alone:
+   * a second conversion would wrap a 12-byte header around one that is
+   * already there.
+   */
+  function fixTranscriptForDtls() {
     let t = tls.context.transcript;
     for (let i = 0; i < t.length; i++) {
-      if (i < transcriptMsgSeqs.length) {
-        t[i] = build_dtls_handshake(t[i], transcriptMsgSeqs[i]);
-      }
+      if (i >= transcriptMsgSeqs.length) continue;
+      let e = t[i];
+      if (!e || e.length < 4) continue;
+      // A DTLS entry is 12 + body; a TLS entry is 4 + body. The declared
+      // length lives in the same place in both, so comparing it against the
+      // actual size tells them apart without guessing.
+      let declared = (e[1] << 16) | (e[2] << 8) | e[3];
+      if (e.length === declared + 12) continue;   // already DTLS format
+      t[i] = build_dtls_handshake(e, transcriptMsgSeqs[i]);
     }
   }
 
+  // Kept for callers that still use the old name.
+  function fixTranscriptForDtls12() { fixTranscriptForDtls(); }
+
 
   // ============================================================
   //  Key derivation
   // ============================================================
 
-  function deriveEpochKeys(secret) {
-    let cs = TLS_CIPHER_SUITES[ctx.cipherSuite];
-    let empty = new Uint8Array(0);
-    let key = hkdf_expand_label(cs.hash, secret, 'key', empty, cs.keylen);
-    let iv = hkdf_expand_label(cs.hash, secret, 'iv', empty, 12);
+  /**
+   * RFC 9147 §5.9: DTLS 1.3 derives with the "dtls13" label prefix (no trailing
+   * space), NOT TLS 1.3's "tls13 ". Using the TLS prefix yields a handshake in
+   * which every message parses and the transcripts match on both sides, and
+   * only the keys differ — the peer reports "bad record MAC" and nothing else.
+   * DTLS 1.2 does not use HKDF-Expand-Label at all (it uses the 1.2 PRF), so
+   * the branch only has to distinguish 1.3.
+   */
+  function dtlsLabelPrefix() {
+    return ctx.selectedVersion === DTLS_VERSION.DTLS1_3
+      ? LABEL_PREFIX_DTLS13
+      : LABEL_PREFIX_TLS13;
+  }
 
-    let result = { key, iv };
+  function deriveEpochKeys(secret) {
+    let lp = dtlsLabelPrefix();
+    // record.js owns "traffic secret -> key + iv" and already exports it. This
+    // function used to re-derive both inline, which is the same two HKDF calls
+    // with the same arguments in a second place — precisely the shape of the
+    // label-prefix bug, where one copy of a derivation was fixed and another
+    // was not. Only the DTLS-specific extras belong here.
+    let result = deriveKeys(secret, ctx.cipherSuite, lp);
 
     // DTLS 1.3: derive sn_key for record number encryption
     if (ctx.selectedVersion === DTLS_VERSION.DTLS1_3) {
-      result.snKey = derive_sn_key(cs.hash, secret, ctx.cipherSuite);
+      result.snKey = derive_sn_key(TLS_CIPHER_SUITES[ctx.cipherSuite].hash, secret,
+                                   ctx.cipherSuite, lp);
       result.algo = getAeadAlgo(ctx.cipherSuite);
     }
 
     return result;
   }
 
+  /**
+   * The DTLS epoch a given key generation belongs to.
+   *
+   * DTLS 1.3 (RFC 9147 §6.1) numbers epochs 0=plaintext, 1=early data,
+   * 2=handshake, 3=application. DTLS 1.2 uses a single encrypted epoch 1.
+   * Which numbering applies depends on the negotiated version, so this must
+   * resolve the version FIRST and never assume a previous sync happened.
+   *
+   * The two callers used to differ: the handshake-secrets handler synced the
+   * version from the TLS session, the application-secrets handler did not sync
+   * at all. That asymmetry is only harmless while the version happens to be
+   * committed by the time each event fires. When it is not — the TLS engine
+   * commits negotiated values at the END of a reactive pass, and these events
+   * are emitted DURING one — the keys are filed under epoch 1 while records are
+   * later built for epoch 2/3. buildRecord then finds no keys, returns null,
+   * and the record is dropped silently: the peer sees nothing at all and times
+   * out. One helper, so both generations decide the same way.
+   */
+  function dtlsEpochForSecrets(isApplication) {
+    if (ctx.selectedVersion === null && tls.context.selected_version) {
+      ctx.selectedVersion = tls.context.selected_version;
+      // Both DTLS versions hash the DTLS handshake header (RFC 6347 §4.2.6,
+      // RFC 9147 §5.9), so the early TLS-format entries must be rewritten
+      // whichever version was negotiated.
+      if (ctx.selectedVersion === DTLS_VERSION.DTLS1_2) fixTranscriptForDtls();
+    }
+    if (ctx.selectedVersion === DTLS_VERSION.DTLS1_3) return isApplication ? 3 : 2;
+    return 1;
+  }
+
   tls.on('handshakeSecrets', function(localSecret, remoteSecret) {
-    // Ensure version is detected before key derivation
-    if (ctx.selectedVersion === null) ctx.selectedVersion = tls.context.selected_version;
+    let dtlsEpoch = dtlsEpochForSecrets(false);
     ctx.cipherSuite = tls.getCipher();
     ctx.hashName = TLS_CIPHER_SUITES[ctx.cipherSuite].hash;
 
-    let dtlsEpoch = ctx.selectedVersion === DTLS_VERSION.DTLS1_3 ? 2 : 1;
-
     ctx.keys[dtlsEpoch] = {
       write: deriveEpochKeys(localSecret),
       read: deriveEpochKeys(remoteSecret),
@@ -365,16 +535,106 @@ function DTLSSession(options) {
   });
 
   tls.on('appSecrets', function(localSecret, remoteSecret) {
-    let dtlsEpoch = ctx.selectedVersion === DTLS_VERSION.DTLS1_3 ? 3 : 1;
+    let dtlsEpoch = dtlsEpochForSecrets(true);
 
     ctx.keys[dtlsEpoch] = {
       write: deriveEpochKeys(localSecret),
       read: deriveEpochKeys(remoteSecret),
     };
     ctx.writeSeq[dtlsEpoch] = 0;
+
+    // Baseline for KeyUpdate. Everything after this point counts up from here,
+    // per direction.
+    ctx.writeEpoch = dtlsEpoch;
+    ctx.readEpoch = dtlsEpoch;
   });
 
 
+  // ============================================================
+  //  KeyUpdate (RFC 9147 §8)
+  // ============================================================
+  //
+  // TLSSession derives the new traffic secret and emits 'keyUpdate'; the DTLS
+  // layer owns everything the epoch implies. Nothing consumed this event
+  // before, so a KeyUpdate updated the session's notion of the traffic secret
+  // while the record layer kept protecting and deprotecting with the old keys.
+  // That is worse than not implementing it: on DTLS an undeprotectable record
+  // is silently discarded (§4.5.2), so the symptom is a connection that simply
+  // stops carrying data, with no alert and no error anywhere.
+
+  tls.on('keyUpdate', function(info) {
+    // DTLS 1.2 has no KeyUpdate; the TLS session only emits this for 1.3, but
+    // the guard keeps the epoch arithmetic below unreachable on the 1.2 path.
+    if (ctx.selectedVersion !== DTLS_VERSION.DTLS1_3) return;
+    if (!info || !info.secret) return;
+    if (ctx.writeEpoch === null || ctx.readEpoch === null) return;
+
+    if (info.direction === 'send') {
+      // §8: only one KeyUpdate may be in flight. requestKeyUpdate() below
+      // refuses up front; reaching here with one pending means the TLS session
+      // rotated its secret anyway (e.g. an auto-response to the peer's
+      // update_requested while ours was still unacknowledged), which would
+      // strand an epoch. Say so rather than silently losing the connection.
+      if (ctx.pendingWriteEpoch !== null) {
+        ev.emit('error', new Error(
+          'DTLS: a KeyUpdate is already awaiting acknowledgement (RFC 9147 §8)'));
+        return;
+      }
+      let next = ctx.writeEpoch + 1;
+      // Install the new write keys, but keep protecting with the old epoch
+      // until the peer ACKs (§8). ctx.keys[next] may already carry a .read
+      // half from the peer's own update — merge, never overwrite.
+      ctx.keys[next] = Object.assign({}, ctx.keys[next], { write: deriveEpochKeys(info.secret) });
+      ctx.writeSeq[next] = 0;
+      ctx.pendingWriteEpoch = next;
+
+    } else if (info.direction === 'receive') {
+      let next = ctx.readEpoch + 1;
+      ctx.keys[next] = Object.assign({}, ctx.keys[next], { read: deriveEpochKeys(info.secret) });
+      ctx.readEpoch = next;
+      // The previous epoch's read keys are deliberately RETAINED. §8: records
+      // already in flight under the old epoch must still deprotect, and our
+      // ACK may be lost, so the peer may retransmit under the old keys.
+    }
+  });
+
+  /** Arm the post-handshake retransmit for an unacknowledged KeyUpdate. */
+  function armKeyUpdateRetransmit(payload, epoch) {
+    cancelKeyUpdateRetransmit();
+    ctx.keyUpdateFlight = {
+      payload: payload, epoch: epoch,
+      attempts: 0, timeout: ctx.retransmitTimeout, timer: null,
+    };
+    scheduleKeyUpdateRetransmit();
+  }
+
+  function scheduleKeyUpdateRetransmit() {
+    let f = ctx.keyUpdateFlight;
+    if (!f) return;
+    f.timer = setTimeout(function () {
+      if (!ctx.keyUpdateFlight) return;
+      if (f.attempts >= ctx.maxRetransmits) {
+        ev.emit('error', new Error('DTLS: KeyUpdate was never acknowledged'));
+        cancelKeyUpdateRetransmit();
+        return;
+      }
+      f.attempts++;
+      // Rebuild rather than replay: a retransmission is a NEW record and needs
+      // a fresh sequence number, or the peer's replay window rejects it.
+      let record = buildRecord(f.epoch, CT.HANDSHAKE, f.payload);
+      if (record) { _ldbgTx(record, 'keyupdate-rtx'); ev.emit('packet', record); }
+      f.timeout = Math.min(f.timeout * 2, 60000);
+      scheduleKeyUpdateRetransmit();
+    }, f.timeout);
+    if (f.timer && typeof f.timer.unref === 'function') f.timer.unref();
+  }
+
+  function cancelKeyUpdateRetransmit() {
+    if (ctx.keyUpdateFlight && ctx.keyUpdateFlight.timer) clearTimeout(ctx.keyUpdateFlight.timer);
+    ctx.keyUpdateFlight = null;
+  }
+
+
   // ============================================================
   //  Outgoing: TLSSession message → DTLS datagram
   // ============================================================
@@ -400,7 +660,11 @@ function DTLSSession(options) {
     if (tlsEpoch === 0) {
       dtlsEpoch = 0;
     } else if (ctx.selectedVersion === DTLS_VERSION.DTLS1_3) {
-      dtlsEpoch = tlsEpoch === 1 ? 2 : 3;  // epoch 2=handshake, 3=app
+      // epoch 2 = handshake. Anything above rides the CURRENT application
+      // epoch, which is 3 until a KeyUpdate moves it to 4, 5, ... Hardcoding 3
+      // meant every post-handshake message stayed on the pre-rekey epoch.
+      dtlsEpoch = (tlsEpoch === 1) ? 2
+                : (ctx.writeEpoch !== null ? ctx.writeEpoch : 3);
     } else {
       dtlsEpoch = 1;  // DTLS 1.2: epoch 1 for all encrypted
     }
@@ -443,10 +707,41 @@ function DTLSSession(options) {
     let frags = fragmentMessage(dtlsMsg, data, seq);
 
     // Build DTLS records and emit
+    // RFC 9147 §5.8.4: post-handshake messages do NOT belong to the handshake
+    // flight. Each category gets an independent state machine; folding a
+    // KeyUpdate into currentFlight would make a handshake retransmission
+    // replay it, and a KeyUpdate ACK cancel the handshake's timer.
+    let isPostHandshakeKU = (type === 'key_update' &&
+                             ctx.selectedVersion === DTLS_VERSION.DTLS1_3);
+    if (isPostHandshakeKU) {
+      for (let i = 0; i < frags.length; i++) {
+        let kuRecord = buildRecord(dtlsEpoch, CT.HANDSHAKE, frags[i]);
+        if (kuRecord) { _ldbgTx(kuRecord, 'keyupdate'); ev.emit('packet', kuRecord); }
+      }
+      // KeyUpdate must be acknowledged (§8), so it is retransmitted on its own
+      // timer until an ACK arrives. Only the last fragment is tracked; a
+      // KeyUpdate body is 1 byte and never fragments in practice.
+      armKeyUpdateRetransmit(frags[frags.length - 1], dtlsEpoch);
+      return;
+    }
+
     for (let i = 0; i < frags.length; i++) {
       let record = buildRecord(dtlsEpoch, CT.HANDSHAKE, frags[i]);
-      ctx.currentFlight.push(record);
-      ev.emit('packet', record);
+      // The flight captures the fragment, not the record — see currentFlight.
+      ctx.currentFlight.push({ epoch: dtlsEpoch, contentType: CT.HANDSHAKE, payload: frags[i] });
+      if (record) {
+        _ldbgTx(record, 'L543'); ev.emit('packet', record);
+      } else {
+        // buildRecord refused to build (no keys for an encrypted epoch).
+        // Dropping the record here without a word is how a key-epoch mismatch
+        // turns into an unexplained peer timeout instead of a diagnosable
+        // failure: nothing reaches the wire and nothing is reported. Surface
+        // it — the handshake cannot proceed either way.
+        ev.emit('error', new Error(
+          'DTLS: could not build outgoing handshake record for epoch ' + dtlsEpoch +
+          ' — no keys installed for that epoch'));
+        return;
+      }
     }
 
     // Start retransmit timer after sending flight messages.
@@ -476,8 +771,21 @@ function DTLSSession(options) {
   function buildRecord(epoch, contentType, payload) {
     let epochKeys = ctx.keys[epoch];
 
+
     if (!epochKeys) {
-      // No keys → plaintext record
+      // DTLS 1.3 epochs 2 (handshake) and 3 (application) are ALWAYS
+      // encrypted — they carry the unified header (first byte 0x2c–0x2f). If
+      // we reach here without keys for such an epoch, emitting a classic
+      // 13-byte plaintext header (first byte = content type, e.g. 0x16/0x1a)
+      // would make the peer reject the record as "bad type byte" (RFC 9147
+      // §4). That only happens on a caller ordering bug (record built before
+      // its epoch's keys were installed); surface it instead of putting a
+      // malformed record on the wire. Epoch 0 is legitimately plaintext.
+      if (ctx.selectedVersion === DTLS_VERSION.DTLS1_3 && epoch >= 2) {
+        ev.emit('error', new Error('DTLS 1.3: attempted to build epoch ' + epoch + ' record before keys installed'));
+        return null;
+      }
+      // No keys → plaintext record (epoch 0, or DTLS 1.2 pre-CCS)
       return buildDtlsPlaintext(contentType, epoch, nextWriteSeq(epoch), payload);
     }
 
@@ -538,7 +846,12 @@ function DTLSSession(options) {
    */
   function sendAlertRecord(epoch, alertData) {
     let record = buildRecord(epoch, CT.ALERT, alertData);
-    ev.emit('packet', record);
+    // buildRecord returns null when it refuses to emit a malformed record
+    // (DTLS 1.3 epoch >= 2 with no keys installed). Emitting that null as a
+    // packet pushes `null` into the transport; drop it instead — we already
+    // surfaced the reason through 'error'.
+    if (!record) return;
+    _ldbgTx(record, 'L664'); ev.emit('packet', record);
   }
 
   /**
@@ -555,12 +868,14 @@ function DTLSSession(options) {
     }
     let record = buildDtlsPlaintext(CT.CHANGE_CIPHER_SPEC, 0, nextWriteSeq(0), new Uint8Array([1]));
     // RFC 6347 §4.2.4: the CCS is part of the flight and MUST be included
-    // when the flight is retransmitted. Previously it was emitted but never
-    // captured, so a retransmitted final flight arrived WITHOUT the cipher-
-    // spec change and the peer could never decrypt the accompanying
-    // Finished — an unrecoverable stall under single-datagram loss.
-    ctx.currentFlight.push(record);
-    ev.emit('packet', record);
+    // when the flight is retransmitted. Captured as a descriptor (epoch 0,
+    // plaintext), so resendFlight rebuilds it with a fresh seq like every
+    // other record. Previously it was emitted but never captured, so a
+    // retransmitted final flight arrived WITHOUT the cipher-spec change and
+    // the peer could never decrypt the accompanying Finished — an
+    // unrecoverable stall under single-datagram loss.
+    ctx.currentFlight.push({ epoch: 0, contentType: CT.CHANGE_CIPHER_SPEC, payload: new Uint8Array([1]) });
+    _ldbgTx(record, 'L688'); ev.emit('packet', record);
   }
 
 
@@ -599,9 +914,47 @@ function DTLSSession(options) {
     // NewSessionTicket etc. are optional and skipped here for simplicity).
     let ackable = [];
 
+    // Whether these records arrived AFTER the handshake must be decided here,
+    // before the loop — not after it. The datagram that completes the
+    // handshake flips ctx.state to 'connected' partway through, so reading the
+    // state afterwards misclassifies the handshake's own epoch-2 records as
+    // post-handshake and ACKs them inside the application-data epoch. That is
+    // the spurious epoch-3 ACK that makes a peer answer decode_error on the
+    // NEXT record — so a perfectly good SCTP COOKIE_ECHO takes the blame.
+    let wasConnectedOnEntry = (ctx.state === 'connected');
+
     for (let i = 0; i < records.length; i++) {
+      // A record we could not decrypt when the datagram was parsed. Keys may
+      // have arrived since — processing an earlier record in THIS datagram
+      // (the ServerHello) is exactly what installs them. Retry now, in order,
+      // so a peer that packs its whole flight into one datagram is handled
+      // without waiting for a retransmit.
+      if (records[i].deferred) {
+        let epochKeys = ctx.keys[records[i].epoch];
+        let readKeys = epochKeys ? epochKeys.read : null;
+        if (!readKeys) continue;                 // still unreadable — let the peer retransmit
+        let dec = null;
+        try { dec = decryptEncryptedDtls13(records[i].raw, readKeys); } catch (e) { dec = null; }
+        if (!dec) continue;
+        records[i] = {
+          type: dec.type, epoch: dec.epoch, seq: dec.seq,
+          content: dec.content, encrypted: true, deferred: false,
+        };
+      }
+
+      // NEVER ACK THE FIRST FLIGHT (RFC 9147 §7.1): "ACKs MUST NOT be
+      // sent for the ClientHello". The first flight is acknowledged by
+      // the RESPONSE to it — the ServerHello — and a peer that receives
+      // an ACK where none belongs answers decode_error.
+      // Epoch 0 records are exactly that first flight: everything later
+      // is protected under epoch 2 or above. This only bites when the
+      // ClientHello is large enough to FRAGMENT, because a single-record
+      // flight is consumed before any ACK decision is made — which is
+      // why a two-way call worked and an SFU, whose extra transceivers
+      // push the ClientHello past the MTU, did not.
       if (records[i].type === CT.HANDSHAKE &&
-          ctx.selectedVersion === DTLS_VERSION.DTLS1_3) {
+          ctx.selectedVersion === DTLS_VERSION.DTLS1_3 &&
+          records[i].epoch > 0) {
         ackable.push({ epoch: records[i].epoch, seq: records[i].seq });
       }
 
@@ -626,8 +979,43 @@ function DTLSSession(options) {
     // We ACK from the highest epoch for which we already have write keys (so the
     // ACK itself is protected once handshake keys exist; epoch 0 before that).
     if (ackable.length > 0) {
-      let ackEpoch = ctx.keys[3] ? 3 : (ctx.keys[2] ? 2 : 0);
-      sendAck(ackEpoch, ackable);
+      // ACKs RIDE THE HANDSHAKE EPOCH (RFC 9147 §7): they acknowledge
+      // handshake records, so epoch 2 once handshake keys exist and
+      // epoch 0 before that — never epoch 3. Picking "the highest epoch
+      // we have keys for" sent them under APPLICATION-DATA protection,
+      // where the peer decrypts with app keys and finds a content type
+      // that does not belong. Chrome answers decode_error.
+      // This shows up the moment a ClientHello is large enough to be
+      // FRAGMENTED — an SFU with several transceivers crosses the MTU
+      // and a two-way call does not, which is exactly why bidirectional
+      // worked and party mode did not.
+      // Post-handshake (§7.1: "For post-handshake messages, ACKs SHOULD be
+      // sent once for each received and processed handshake record") the
+      // handshake epoch is gone and §7 requires the HIGHEST available sending
+      // epoch. During the handshake it is still epoch 2, or 0 before keys.
+      // RFC 9147 §7.1 lists the flights that are IMPLICITLY acknowledged by
+      // the responding flight, and the client's final flight is pointedly not
+      // among them: "In general, flights MUST be ACKed unless they are
+      // implicitly acknowledged", excepting "handshake flights other than the
+      // client's final flight of the main handshake".
+      //
+      // So the two roles need opposite answers here, which is why a
+      // state-only test could not get both right:
+      //   client — the server's flight is implicitly acked by our own final
+      //            flight, so an explicit ACK is both redundant and (at the
+      //            application epoch) actively harmful;
+      //   server — the client's final flight has no responding flight, so
+      //            without an explicit ACK the client retransmits it forever.
+      // §7 then fixes the epoch: after the handshake, the highest available
+      // sending epoch.
+      let justCompleted = (!wasConnectedOnEntry && ctx.state === 'connected');
+      let finalFlightAck = isServer && justCompleted;
+      let atAppEpoch = wasConnectedOnEntry || finalFlightAck;
+
+      let ackEpoch = atAppEpoch
+        ? (ctx.writeEpoch !== null ? ctx.writeEpoch : 3)
+        : (ctx.keys[2] ? 2 : 0);
+      sendAck(ackEpoch, ackable, atAppEpoch);
     }
   }
 
@@ -669,6 +1057,12 @@ function DTLSSession(options) {
     } else if (record.type === CT.ALERT) {
       let level = record.content[0];
       let desc = record.content[1];
+      // Name the alert either way. A close_notify is a CLEAN shutdown and
+      // a failure is not, but both present to the application as "the
+      // connection ended" — and telling them apart is the difference
+      // between "the peer hung up" and "the peer rejected us".
+      _ldbg('RX Alert level=' + level + ' desc=' + desc +
+            (desc === 0 ? ' (close_notify — clean shutdown)' : ' (failure)'));
       if (desc === 0) {
         // close_notify
         ctx.state = 'closed';
@@ -751,9 +1145,7 @@ function DTLSSession(options) {
       // bounds the total effort; the resend rate is naturally bounded by
       // the peer's own retransmission schedule. DTLS 1.3 is excluded —
       // it uses explicit ACKs (RFC 9147 §7) instead of flight inference.
-      for (let f = 0; f < ctx.currentFlight.length; f++) {
-        ev.emit('packet', ctx.currentFlight[f]);
-      }
+      resendFlight();
     }
   }
 
@@ -828,6 +1220,7 @@ function DTLSSession(options) {
       coveredAfter += merged[ca][1] - merged[ca][0];
     }
 
+
     // Complete when a single range covers [0, totalLength).
     if (merged.length === 1 && merged[0][0] === 0 && merged[0][1] === frag.totalLength) {
       delete ctx.fragments[key];
@@ -871,11 +1264,45 @@ function DTLSSession(options) {
     //
     // Note: msg_seq is NOT advanced for a rejected/HVR-triggering ClientHello, so
     // the client's retried CH (which reuses msg_seq per RFC 6347) is still accepted.
-    if (type === 1 && isServer && options.useCookies === true &&
-        ctx.selectedVersion !== DTLS_VERSION.DTLS1_3) {
-
+    if (type === 1 && isServer) {
       let ch = null;
       try { ch = parse_hello({ kind: 'client', body: body }); } catch (e) { ch = null; }
+
+      // Does this ClientHello offer DTLS 1.3?
+      //
+      // RULE: a decision derived from an incoming message is read from that
+      // message, never from state the message itself is about to establish.
+      // (Stated in full next to params_to_set in tls_session.js; this is the
+      // fourth bug it has caused.) Read it from the MESSAGE, never
+      // from ctx.selectedVersion — when the first ClientHello arrives nothing
+      // has been negotiated yet, so a state-based test reads null and fails
+      // OPEN. That matters because the two rules below are MUST-level and
+      // version-specific.
+      let offersDtls13 = false;
+      if (ch && Array.isArray(ch.supported_versions)) {
+        offersDtls13 = ch.supported_versions.indexOf(DTLS_VERSION.DTLS1_3) >= 0;
+      }
+
+      // RFC 9147 §5.3: "A DTLS 1.3-only client MUST set the legacy_cookie field
+      // to zero length. If a DTLS 1.3 ClientHello is received with any other
+      // value in this field, the server MUST abort the handshake with an
+      // 'illegal_parameter' alert." DTLS 1.3 carries cookies in the `cookie`
+      // EXTENSION; the legacy body field is vestigial and must stay empty.
+      if (offersDtls13 && ch && ch.dtls_cookie && ch.dtls_cookie.length > 0) {
+        tls.sendAlert(2, 47); // fatal, illegal_parameter
+        ev.emit('error', new Error(
+          'DTLS 1.3 ClientHello carries a non-empty legacy_cookie (' +
+          ch.dtls_cookie.length + ' bytes) — RFC 9147 §5.3 requires zero length'));
+        return false;
+      }
+
+      // RFC 9147 §5.1: "DTLS 1.3-compliant implementations MUST NOT use the
+      // HelloVerifyRequest to execute a return-routability check." DTLS 1.3
+      // does return-routability with HelloRetryRequest + the cookie extension
+      // instead. The old guard tested ctx.selectedVersion, which is null here,
+      // so a DTLS 1.3 handshake could still be answered with an HVR.
+      if (options.useCookies === true && !offersDtls13) {
+
       let incomingCookie = (ch && ch.dtls_cookie) ? ch.dtls_cookie : new Uint8Array(0);
 
       if (incomingCookie.length === 0) {
@@ -911,9 +1338,10 @@ function DTLSSession(options) {
       // feedHandshakeToTls records the incoming wire seq and outgoing
       // messages record message_sent_seq at emission — which is exactly
       // what the Finished MAC hashes (RFC 6347 §4.2.6).
-      ctx.nextReadMsgSeq = 1;
-      tls.context.message_sent_seq = 1;
-      // Fall through and process the ClientHello normally.
+        ctx.nextReadMsgSeq = 1;
+        tls.context.message_sent_seq = 1;
+        // Fall through and process the ClientHello normally.
+      }
     }
 
     // ---- In-order delivery (RFC 6347 §4.2.4 / RFC 9147 §5.2) ----
@@ -1014,7 +1442,7 @@ function DTLSSession(options) {
     // HVR always uses msg_seq 0 and is sent in the clear (epoch 0).
     let hvrMsg = build_dtls_handshake(build_message(3, build_hello_verify_request({ cookie: cookie })), 0);
     let record = buildDtlsPlaintext(CT.HANDSHAKE, 0, nextWriteSeq(0), hvrMsg);
-    ev.emit('packet', record);
+    _ldbgTx(record, 'L1194'); ev.emit('packet', record);
   }
 
   /**
@@ -1077,8 +1505,8 @@ function DTLSSession(options) {
     // Build DTLS message and send — msg_seq 1 per the RFC figure above.
     let dtlsMsg = build_dtls_handshake(ch2, 1);
     let record = buildRecord(0, CT.HANDSHAKE, dtlsMsg);
-    ctx.currentFlight = [record];
-    ev.emit('packet', record);
+    ctx.currentFlight = [{ epoch: 0, contentType: CT.HANDSHAKE, payload: dtlsMsg }];
+    if (record) { _ldbgTx(record, 'L1258'); ev.emit('packet', record); }
 
     tls.context.message_sent_seq = 2;
     startRetransmitTimer();
@@ -1089,8 +1517,45 @@ function DTLSSession(options) {
   //  Flight tracking + retransmission
   // ============================================================
 
+  /**
+   * Rebuild and re-emit the current flight with FRESH record sequence numbers.
+   * See currentFlight's comment for why re-encryption (not byte replay) is
+   * mandatory. Each descriptor goes back through buildRecord, which pulls the
+   * next write seq for its epoch — so a retransmitted DTLS 1.3 record gets a
+   * new nonce, and a monotonic seq the receiver can reconstruct.
+   */
+  function resendFlight() {
+    // NEVER AFTER THE HANDSHAKE COMPLETES. Once we are connected the
+    // handshake flight is finished by definition, and re-emitting it
+    // sends HANDSHAKE content inside an APPLICATION-DATA epoch — the
+    // peer decrypts a record with its app-data keys and finds a message
+    // it cannot place. Chrome tolerated one and then answered
+    // decode_error on the next SCTP record, which read as an SCTP
+    // problem for several rounds and was not one: the giveaway is a
+    // record in the log with no matching sctp->dtls line, because the
+    // payload never came from the application at all.
+    // RFC 9147 §5.8: retransmission is bounded by the handshake; after
+    // it, ACKs are the mechanism, not a timer.
+    if (ctx.state === 'connected' || ctx.state === 'closed') {
+      cancelRetransmit();
+      return;
+    }
+    for (let i = 0; i < ctx.currentFlight.length; i++) {
+      let f = ctx.currentFlight[i];
+      let record = buildRecord(f.epoch, f.contentType, f.payload);
+      if (record) { _ldbgTx(record, 'L1280'); ev.emit('packet', record); }
+    }
+  }
+
   function startRetransmitTimer() {
     cancelRetransmit();
+    // ONE GATE, AT THE SOURCE. Four call sites arm this timer and only
+    // one of them checks the state, so a timer armed while the handshake
+    // was still running could fire after it finished and re-emit the
+    // flight into the application-data epoch. Refusing to arm once
+    // connected (or closed) covers every caller, including any added
+    // later, without each having to remember the rule.
+    if (ctx.state === 'connected' || ctx.state === 'closed') return;
     ctx.retransmitTimer = setTimeout(function() {
       if (ctx.retransmitCount >= ctx.maxRetransmits) {
         ev.emit('error', new Error('DTLS handshake timeout — max retransmits exceeded'));
@@ -1099,10 +1564,8 @@ function DTLSSession(options) {
         return;
       }
 
-      // Retransmit entire current flight
-      for (let i = 0; i < ctx.currentFlight.length; i++) {
-        ev.emit('packet', ctx.currentFlight[i]);
-      }
+      // Retransmit entire current flight with fresh record seqs.
+      resendFlight();
 
       ctx.retransmitCount++;
       ctx.retransmitTimeout = Math.min(ctx.retransmitTimeout * 2, 60000);
@@ -1132,16 +1595,52 @@ function DTLSSession(options) {
 
   function processAck(content) {
     let acks = parseDtlsAck(content);
-    // ACK received — flight was acknowledged
+
+    // An outstanding KeyUpdate is what this ACK is for: §8 forbids protecting
+    // anything with the new keys until it arrives, so THIS is the moment the
+    // new epoch becomes live. Keys were installed when the KeyUpdate was sent;
+    // only the switch happens here.
+    if (ctx.pendingWriteEpoch !== null) {
+      ctx.writeEpoch = ctx.pendingWriteEpoch;
+      ctx.pendingWriteEpoch = null;
+      cancelKeyUpdateRetransmit();
+      ev.emit('keyUpdate', { direction: 'send', epoch: ctx.writeEpoch });
+      return;
+    }
+
+    // Everything else keeps the original behaviour verbatim. In particular the
+    // ACK for the client's final flight (which RFC 9147 §7.1 requires the peer
+    // to send explicitly, and which arrives at the application epoch) must
+    // still cancel that flight's retransmit timer.
     cancelRetransmit();
     startNewFlight();
   }
 
-  function sendAck(epoch, recordsToAck) {
+  function sendAck(epoch, recordsToAck, postHandshake) {
     if (ctx.selectedVersion !== DTLS_VERSION.DTLS1_3) return;
+    // ACKs BELONG TO THE HANDSHAKE (RFC 9147 §7). They acknowledge
+    // handshake records, and once the handshake is complete there is
+    // nothing left to acknowledge — but this kept firing afterwards and
+    // put an ACK record inside the APPLICATION-DATA epoch. The peer
+    // decrypts it with app-data keys, finds a content type that has no
+    // business there, and the stream is poisoned: Chrome tolerated it
+    // and then answered decode_error on the next record, which made a
+    // perfectly good SCTP COOKIE_ECHO look like the culprit for several
+    // rounds. The giveaway in the log is a record with no matching
+    // sctp->dtls line — the payload never came from the application.
+    // ...that reasoning applies to HANDSHAKE flights. Post-handshake messages
+    // are a separate case the original guard swept up with them: KeyUpdate,
+    // NewSessionTicket and friends have no responding flight to acknowledge
+    // them implicitly, so §7.1 requires an explicit ACK — without one the peer
+    // retransmits its KeyUpdate forever and never activates its new keys.
+    // `postHandshake` is set only for records actually received and processed
+    // after the handshake, so the spurious-ACK bug this guard was written for
+    // cannot return through it.
+    if (!postHandshake && (ctx.state === 'connected' || ctx.state === 'closed')) return;
+    if (ctx.state === 'closed') return;
     let payload = buildDtlsAck(recordsToAck);
     let record = buildRecord(epoch, CT.ACK, payload);
-    ev.emit('packet', record);
+    _ldbgTx(record, 'L1334'); ev.emit('packet', record);
   }
 
 
@@ -1169,6 +1668,13 @@ function DTLSSession(options) {
   });
 
   tls.on('error', function(e) {
+    // The peer's REASON, spelled out. When BoringSSL rejects part of our
+    // flight it sends an alert and closes; without printing it here the
+    // only symptom is a connection that dies after a handshake that
+    // looked complete, which is exactly the DTLS 1.3 interop case.
+    _ldbg('ERROR ' + (e && e.message ? e.message : e) +
+          (e && e.alertDescription != null ? ' alertDesc=' + e.alertDescription : '') +
+          (e && e.code ? ' code=' + e.code : ''));
     ev.emit('error', e);
   });
 
@@ -1188,9 +1694,11 @@ function DTLSSession(options) {
     }
     if (typeof data === 'string') data = new TextEncoder().encode(data);
 
-    let epoch = ctx.selectedVersion === DTLS_VERSION.DTLS1_3 ? 3 : 1;
+    let epoch = ctx.selectedVersion === DTLS_VERSION.DTLS1_3
+      ? (ctx.writeEpoch !== null ? ctx.writeEpoch : 3)
+      : 1;
     let record = buildRecord(epoch, CT.APPLICATION_DATA, data);
-    ev.emit('packet', record);
+    _ldbgTx(record, 'L1383'); ev.emit('packet', record);
   }
 
 
@@ -1200,10 +1708,30 @@ function DTLSSession(options) {
 
   function close() {
     if (ctx.state === 'closed') return;
-    let epoch = ctx.state === 'connected' ? (ctx.selectedVersion === DTLS_VERSION.DTLS1_3 ? 3 : 1) : 0;
+    // Choose the epoch by what the PEER can read, not by whether WE consider
+    // the handshake finished — the same rule the TLS branch uses for alerts.
+    //
+    // "not connected yet" does not mean "no keys": once handshake keys exist
+    // the peer has switched to reading protected records, and a plaintext
+    // close_notify arrives with a classic DTLSPlaintext header where the peer
+    // requires the RFC 9147 §4 unified header. It then reports a bad record
+    // type instead of a clean shutdown. Mirror the ACK path, which already
+    // picks the highest epoch we hold write keys for.
+    let epoch;
+    if (ctx.selectedVersion === DTLS_VERSION.DTLS1_3) {
+      // After a KeyUpdate the live epoch is 4, 5, ... — the peer has moved on
+      // and no longer reads epoch 3, so a close_notify sent there is dropped
+      // and the shutdown looks like a timeout instead of a clean close.
+      epoch = (ctx.writeEpoch !== null && ctx.keys[ctx.writeEpoch])
+        ? ctx.writeEpoch
+        : (ctx.keys[3] ? 3 : (ctx.keys[2] ? 2 : 0));
+    } else {
+      epoch = ctx.keys[1] ? 1 : 0;
+    }
     sendAlertRecord(epoch, new Uint8Array([1, 0])); // warning, close_notify
     ctx.state = 'closed';
     cancelRetransmit();
+    cancelKeyUpdateRetransmit();
     ev.emit('close');
   }
 
@@ -1233,6 +1761,31 @@ function DTLSSession(options) {
     /** Send application data (after connect). */
     send: send,
 
+    /**
+     * Request a TLS 1.3 KeyUpdate (RFC 9147 §8).
+     *
+     * Returns false without doing anything if the session is not a connected
+     * DTLS 1.3 association, or if an earlier KeyUpdate has not been
+     * acknowledged yet — §8 permits only one in flight. The new epoch does not
+     * become active on send; it activates when the peer's ACK arrives.
+     *
+     * @param {boolean} [requestPeer] also ask the peer to update its own keys
+     * @returns {boolean} whether the update was initiated
+     */
+    requestKeyUpdate: function(requestPeer) {
+      if (ctx.selectedVersion !== DTLS_VERSION.DTLS1_3) return false;
+      if (ctx.state !== 'connected') return false;
+      if (ctx.pendingWriteEpoch !== null) return false;
+      tls.requestKeyUpdate(!!requestPeer);
+      return true;
+    },
+
+    /** Current epoch used to protect outgoing records (null before connect). */
+    getWriteEpoch: function() { return ctx.writeEpoch; },
+
+    /** Highest epoch for which read keys are installed (null before connect). */
+    getReadEpoch: function() { return ctx.readEpoch; },
+
     /** Close the DTLS session. */
     close: close,
 
@@ -1255,6 +1808,16 @@ function DTLSSession(options) {
       return tls.exportKeyingMaterial(length, label, context_value);
     },
 
+    /**
+     * The negotiated DTLS-SRTP protection profile (RFC 5764), or null.
+     * Surfaced here because DTLS-SRTP is the reason the exporter exists for
+     * this transport — a caller that can export keying material must also be
+     * able to learn which profile those keys are for.
+     */
+    getSelectedSrtpProfile: function() {
+      return tls.getSelectedSrtpProfile();
+    },
+
     /** Peer's hello extensions: [{ type, name, data, value }]. */
     getRemoteExtensions: function() { return tls.getRemoteExtensions(); },