lemon-tls 0.4.1 → 0.5.5

package/src/dtls_socket.js

@@ -81,6 +81,13 @@ function DTLSSocket(udpSocket, options) {
     ev.emit('session', ticket);
   });
 
+  // Server-side callers use this to inspect the peer's offered extensions
+  // (session.getRemoteExtension) and answer via set_context BEFORE the
+  // ServerHello is built — e.g. DTLS-SRTP's use_srtp (RFC 5764).
+  session.on('clienthello', function(data, message) {
+    ev.emit('clienthello', data, message);
+  });
+
   /**
    * Feed an incoming UDP datagram (filtered by remote address/port).
    * Called by the UDP socket's message handler or by DTLSServer.
@@ -122,6 +129,21 @@ function DTLSSocket(udpSocket, options) {
   self.getALPN = function() { return session.getALPN(); };
   self.getPeerCertificate = function() { return session.getPeerCertificate(); };
 
+  /** RFC 5705 / RFC 8446 §7.5 exporter (Node tls.TLSSocket parity).
+   *  DTLS-SRTP: exportKeyingMaterial(len, 'EXTRACTOR-dtls_srtp') — no context.
+   *  Returns Buffer, or null before secrets are available. */
+  self.exportKeyingMaterial = function(length, label, context_value) {
+    return session.exportKeyingMaterial(length, label, context_value);
+  };
+
+  /** Peer hello extensions / single extension by numeric type. */
+  self.getRemoteExtensions = function() { return session.getRemoteExtensions(); };
+  self.getRemoteExtension = function(type) { return session.getRemoteExtension(type); };
+
+  /** Pass config through to the underlying session (e.g. local_extensions
+   *  from a 'clienthello' handler). */
+  self.set_context = function(opts) { session.set_context(opts); };
+
   /** Access to internal DTLSSession (for advanced use). */
   self.session = session;
 

package/src/record.js

@@ -297,6 +297,37 @@ function getNonce12(salt4, explicit8) {
   return out;
 }
 
+/**
+ * TLS/DTLS 1.2 ChaCha20-Poly1305 nonce (RFC 7905 §2).
+ *
+ * Unlike AES-GCM, ChaCha20-Poly1305 in TLS 1.2 has NO explicit per-record nonce
+ * on the wire. The 12-byte nonce is the record's 64-bit sequence number, left-
+ * padded to 12 bytes, XORed with the 12-byte client/server write IV derived from
+ * the key block. This is the same construction TLS 1.3 uses — the difference from
+ * GCM (salt(4) || explicit(8)) is why the two must be handled separately.
+ *
+ * For DTLS the "sequence number" input is the 16-bit epoch concatenated with the
+ * 48-bit record sequence number, i.e. the same 64-bit value used in the AAD, so
+ * callers pass the full record seq and (for DTLS) fold the epoch into it.
+ */
+function getChachaNonce12(iv12, seq) {
+  const nonce = new Uint8Array(12);
+  nonce.set(iv12, 0);
+  // XOR the 64-bit seq into the LAST 8 bytes (big-endian), leaving the first 4
+  // bytes of the IV untouched — identical layout to TLS 1.3's getNonce.
+  const hi = (seq / 0x100000000) | 0;
+  const lo = seq >>> 0;
+  nonce[4]  ^= (hi >>> 24) & 0xff;
+  nonce[5]  ^= (hi >>> 16) & 0xff;
+  nonce[6]  ^= (hi >>> 8)  & 0xff;
+  nonce[7]  ^=  hi         & 0xff;
+  nonce[8]  ^= (lo >>> 24) & 0xff;
+  nonce[9]  ^= (lo >>> 16) & 0xff;
+  nonce[10] ^= (lo >>> 8)  & 0xff;
+  nonce[11] ^=  lo         & 0xff;
+  return nonce;
+}
+
 /**
  * Encode sequence number as 8-byte big-endian.
  * Perf: uses Number arithmetic (seq < 2^53 is always safe for TLS).
@@ -634,11 +665,36 @@ function buildDtlsAad12(epoch, seq, type, plaintextLen) {
   return aad;
 }
 
-/** Encrypt DTLS 1.2 record payload. Returns: explicit_nonce(8) || ciphertext || tag(16). */
+/** Encrypt DTLS 1.2 record payload. Returns: [explicit_nonce(8) ||] ciphertext || tag(16).
+ *
+ * AES-GCM: prepends an 8-byte explicit nonce (the record seq); nonce = salt(4) || seq(8).
+ * ChaCha20-Poly1305 (RFC 7905): NO explicit nonce on the wire; nonce = iv(12) XOR
+ *   (epoch(16) || seq(48)). Detected by ivSalt length (12 = ChaCha, 4 = GCM).
+ */
 function encryptDtls12(pt, key, ivSalt, epoch, seq, type) {
+  let aad = buildDtlsAad12(epoch, seq, type, pt.length);
+
+  // ChaCha20-Poly1305: full 12-byte IV, no explicit nonce (RFC 7905).
+  if (ivSalt.length === 12) {
+    // DTLS folds the 16-bit epoch above the 48-bit seq to form the 64-bit
+    // sequence input, matching the AAD's epoch||seq (RFC 6347 / RFC 9147).
+    let seq64 = epoch * 0x1000000000000 + seq;
+    let nonce = getChachaNonce12(ivSalt, seq64);
+    let cipher = crypto.createCipheriv('chacha20-poly1305', key, nonce, { authTagLength: 16 });
+    cipher.setAAD(aad, { plaintextLength: pt.length });
+    let ct = cipher.update(pt);
+    cipher.final();
+    let tag = cipher.getAuthTag();
+    // No explicit nonce prefix for ChaCha.
+    let out = new Uint8Array(ct.length + tag.length);
+    out.set(new Uint8Array(ct), 0);
+    out.set(new Uint8Array(tag), ct.length);
+    return out;
+  }
+
+  // AES-GCM: explicit nonce (= record seq) prepended.
   let explicit = seqToBytes(seq);
   let nonce = getNonce12(ivSalt, explicit);
-  let aad = buildDtlsAad12(epoch, seq, type, pt.length);
   let algo = key.length === 16 ? 'aes-128-gcm' : 'aes-256-gcm';
   let cipher = crypto.createCipheriv(algo, key, nonce);
   cipher.setAAD(aad);
@@ -652,8 +708,28 @@ function encryptDtls12(pt, key, ivSalt, epoch, seq, type) {
   return out;
 }
 
-/** Decrypt DTLS 1.2 record fragment. Input: explicit_nonce(8) || ciphertext || tag(16). */
+/** Decrypt DTLS 1.2 record fragment.
+ *  AES-GCM input: explicit_nonce(8) || ciphertext || tag(16).
+ *  ChaCha20 input: ciphertext || tag(16)  (no explicit nonce — RFC 7905).
+ */
 function decryptDtls12(fragment, key, ivSalt, epoch, seq, type) {
+  // ChaCha20-Poly1305: no explicit nonce; nonce = iv(12) XOR (epoch||seq).
+  if (ivSalt.length === 12) {
+    if (fragment.length < 16) throw new Error('DTLS 1.2 ChaCha fragment too short');
+    let ct  = fragment.slice(0, fragment.length - 16);
+    let tag = fragment.slice(fragment.length - 16);
+    let seq64 = epoch * 0x1000000000000 + seq;
+    let nonce = getChachaNonce12(ivSalt, seq64);
+    let aad = buildDtlsAad12(epoch, seq, type, ct.length);
+    let decipher = crypto.createDecipheriv('chacha20-poly1305', key, nonce, { authTagLength: 16 });
+    decipher.setAAD(aad, { plaintextLength: ct.length });
+    decipher.setAuthTag(tag);
+    let pt = decipher.update(ct);
+    decipher.final();
+    return new Uint8Array(pt);
+  }
+
+  // AES-GCM: strip the 8-byte explicit nonce.
   if (fragment.length < 24) throw new Error('DTLS 1.2 fragment too short');
   let explicit = fragment.slice(0, 8);
   let tag = fragment.slice(fragment.length - 16);
@@ -801,10 +877,42 @@ function buildEncryptedDtls13(innerType, plaintext, seq, epoch, keys) {
   return record;
 }
 
+/**
+ * Reconstruct a full DTLS 1.3 record sequence number from its truncated wire
+ * encoding (RFC 9147 §4.2.2).
+ *
+ * @param truncated  the low `bits` bits of the seq as sent on the wire
+ * @param bits       8 or 16 (how many low bits were transmitted)
+ * @param maxSeq     highest full seq already accepted in this epoch (-1 if none)
+ *
+ * Returns the full seq: the value congruent to `truncated` (mod 2^bits) that is
+ * closest to maxSeq+1. This tolerates reordering within half a window in each
+ * direction, which is what the sliding receive window expects.
+ */
+function reconstructDtlsSeq(truncated, bits, maxSeq) {
+  let window = Math.pow(2, bits);          // 256 or 65536
+  let expected = maxSeq + 1;               // where we expect the next record
+  let high = Math.floor(expected / window) * window;
+  let candidate = high + truncated;
+
+  // Pick whichever of {candidate-window, candidate, candidate+window} is nearest
+  // to `expected`, without going negative.
+  let best = candidate;
+  let bestDist = Math.abs(candidate - expected);
+  for (let delta of [-window, window]) {
+    let alt = candidate + delta;
+    if (alt < 0) continue;
+    let dist = Math.abs(alt - expected);
+    if (dist < bestDist) { best = alt; bestDist = dist; }
+  }
+  return best;
+}
+
+
 /**
  * Decrypt a DTLS 1.3 encrypted record.
  * data: full record bytes (starting with unified header byte)
- * keys: { key, iv, snKey, algo? }
+ * keys: { key, iv, snKey, algo?, maxReadSeq? }
  * Returns { epoch, seq, type, content } or null on failure.
  */
 function decryptEncryptedDtls13(data, keys) {
@@ -834,7 +942,19 @@ function decryptEncryptedDtls13(data, keys) {
 
   // Decrypt record number
   let rn = maskRecordNumber(keys.snKey, encRn, ciphertext);
-  let seq = hdr.seqLen2 ? ((rn[0] << 8) | rn[1]) : rn[0];
+  let truncated = hdr.seqLen2 ? ((rn[0] << 8) | rn[1]) : rn[0];
+
+  // RFC 9147 §4.2.2: the wire carries only the low 8 or 16 bits of the record
+  // sequence number. Reconstruct the full value by choosing the candidate
+  // congruent to `truncated` (mod window) that is closest to the highest seq
+  // we've already accepted in this epoch. Without this, seq silently wraps to 0
+  // after 2^16 records and every nonce/AAD past that point is wrong.
+  //
+  // keys.maxReadSeq holds the highest full seq accepted so far (per-epoch key
+  // object). It starts undefined → treated as -1 so the first record maps to
+  // its own truncated value.
+  let seq = reconstructDtlsSeq(truncated, hdr.seqLen2 ? 16 : 8,
+                               (keys.maxReadSeq === undefined ? -1 : keys.maxReadSeq));
 
   // Rebuild AAD with plaintext RN
   let hdrLen = 1 + rnLen + (hdr.hasLength ? 2 : 0);
@@ -863,6 +983,13 @@ function decryptEncryptedDtls13(data, keys) {
     decipher.final();
 
     let inner = parseInnerPlaintext(new Uint8Array(pt));
+
+    // Advance the per-epoch high-water mark only after the tag verified, so a
+    // forged/replayed record number can't poison future reconstruction.
+    if (keys.maxReadSeq === undefined || seq > keys.maxReadSeq) {
+      keys.maxReadSeq = seq;
+    }
+
     return {
       epoch: hdr.epoch,
       seq: seq,
@@ -1018,6 +1145,7 @@ export {
 
   // TLS 1.2
   getNonce12,
+  getChachaNonce12,
   seqToBytes,
   buildAad12,
   encrypt12,

package/src/session/ecdh.js

@@ -28,7 +28,22 @@ function x25519_get_shared_secret(localPrivateRaw, remotePublicRaw) {
   let pubDer  = Buffer.concat([X25519_SPKI_PREFIX, Buffer.from(remotePublicRaw)]);
   let privObj = crypto.createPrivateKey({ key: privDer, format: 'der', type: 'pkcs8' });
   let pubObj  = crypto.createPublicKey({ key: pubDer, format: 'der', type: 'spki' });
-  return new Uint8Array(crypto.diffieHellman({ privateKey: privObj, publicKey: pubObj }));
+  let secret  = new Uint8Array(crypto.diffieHellman({ privateKey: privObj, publicKey: pubObj }));
+
+  // RFC 7748 §6.1: implementations MUST reject an all-zero shared secret. A peer
+  // that sends a low-order/small-order public key can force the X25519 result to
+  // be all zeros — a value it knows in advance — which would let it choose the
+  // key material. The `break` here is safe (does not leak a secret): the peer's
+  // public key is public, so an early exit reveals nothing exploitable.
+  let allZero = true;
+  for (let i = 0; i < secret.length; i++) {
+    if (secret[i] !== 0) { allZero = false; break; }
+  }
+  if (allZero) {
+    throw new Error('X25519: all-zero shared secret — invalid peer public key (RFC 7748 §6.1)');
+  }
+
+  return secret;
 }
 
 /**

package/src/tls_session.js

@@ -21,12 +21,16 @@ import {
   derive_handshake_traffic_secrets_psk_with_hash,
   hkdf_expand_label,
   getHashFn,
+  derive_exporter_master_secret_with_hash,
+  tls13_exporter,
+  tls12_exporter,
 } from './crypto.js';
 
 import {
   concatUint8Arrays,
   arraysEqual,
-  uint8Equal
+  uint8Equal,
+  timingSafeEqualU8
 } from './utils.js';
 
 import * as wire from './wire.js';
@@ -38,6 +42,15 @@ import { x25519_get_public_key, x25519_get_shared_secret, p256_generate_keypair,
 import { build_tls_message, parse_tls_message } from './session/message.js';
 import { encrypt_session_blob, decrypt_session_blob, encode_client_session, decode_client_session } from './session/ticket.js';
 
+// RFC 8446 §4.1.3 downgrade-protection sentinels. A TLS 1.3-capable server that
+// negotiates a lower version stamps one of these into the last 8 bytes of
+// ServerHello.random; a TLS 1.3-capable client that ends up on a lower version
+// MUST reject the handshake if it sees the sentinel. This defeats an active
+// attacker forcing a version downgrade (the sentinel is covered by the server's
+// signature / Finished, so it can't be stripped without breaking the handshake).
+const DOWNGRADE_SENTINEL_TLS12 = new Uint8Array([0x44,0x4F,0x57,0x4E,0x47,0x52,0x44,0x01]); // "DOWNGRD\x01"
+const DOWNGRADE_SENTINEL_TLS11 = new Uint8Array([0x44,0x4F,0x57,0x4E,0x47,0x52,0x44,0x00]); // "DOWNGRD\x00" (TLS 1.1 and below)
+
 // Debug logging — enabled via LEMON_DEBUG=1 env var
 const LEMON_DEBUG = typeof process !== 'undefined' && process.env && process.env.LEMON_DEBUG === '1';
 function dbg(tag, ...args) { if (LEMON_DEBUG) console.error('[LEMON ' + tag + ']', ...args); }
@@ -199,6 +212,7 @@ function TLSSession(options){
 
     // TLS 1.3 resumption
     tls13_master_secret: null,
+    exporter_master_secret: null,     // RFC 8446 §7.1 "exp master" — for exportKeyingMaterial
     resumption_master_secret: null,
     ticket_nonce_counter: 0,
     session_ticket_sent: false,
@@ -363,6 +377,15 @@ function TLSSession(options){
       // Save raw ClientHello + emit event (server side)
       if (context.isServer && message.type === 'client_hello') {
         context.rawClientHello = data;
+        // Make the peer's extensions readable INSIDE the 'clienthello'
+        // handler (getRemoteExtension/getRemoteExtensions) — the main
+        // set_context that stores them runs after this emit, and the
+        // whole point of the event is to let callers inspect the offer
+        // and set answering local_extensions before the ServerHello is
+        // built (e.g. DTLS-SRTP use_srtp, RFC 5764 §4.1.2). The later
+        // set_context stores the identical array; its equality check
+        // makes that a no-op.
+        context.remote_extensions = message.extensions || [];
         ev.emit('clienthello', data, message);
       }
 
@@ -412,12 +435,10 @@ function TLSSession(options){
           dbg('SRV-PSK', 'expected binder:', hexPreview(expectedBinder, 16));
           dbg('SRV-PSK', 'received binder:', hexPreview(pskBinder, 16));
 
-          let binderOk = pskBinder && expectedBinder.length === pskBinder.length;
-          if (binderOk) {
-            for (let bi = 0; bi < expectedBinder.length; bi++) {
-              if (expectedBinder[bi] !== pskBinder[bi]) { binderOk = false; break; }
-            }
-          }
+          // Constant-time binder comparison. A byte-by-byte early-exit compare
+          // would let an attacker recover a valid binder via timing, one byte at
+          // a time. timingSafeEqualU8 always compares the full length.
+          let binderOk = timingSafeEqualU8(expectedBinder, pskBinder);
 
           dbg('SRV-PSK', binderOk ? '✓ BINDER MATCH — psk_accepted' : '✗ BINDER MISMATCH — full handshake');
 
@@ -581,6 +602,28 @@ function TLSSession(options){
         add_remote_key_groups: message.key_groups || []
       });
 
+      // RFC 8446 §4.1.3: downgrade-protection check (client side).
+      // If we offered TLS 1.3 but the server steered us to a lower version, the
+      // server's random must NOT carry the downgrade sentinel — if it does, an
+      // active attacker forced the downgrade. HRR was already handled and
+      // returned above, so `message` here is a genuine ServerHello.
+      if (!context.isServer && message.type === 'server_hello' &&
+          context.local_supported_versions.indexOf(wire.TLS_VERSION.TLS1_3) >= 0 &&
+          context.selected_version !== null &&
+          context.selected_version !== wire.TLS_VERSION.TLS1_3 &&
+          context.selected_version !== wire.DTLS_VERSION.DTLS1_3 &&
+          message.random && message.random.length === 32) {
+
+        let tail = message.random.subarray(24, 32);
+        if (timingSafeEqualU8(tail, DOWNGRADE_SENTINEL_TLS12) ||
+            timingSafeEqualU8(tail, DOWNGRADE_SENTINEL_TLS11)) {
+          dbg('DOWNGRADE', 'sentinel detected in ServerHello.random — aborting');
+          sendAlert(2, wire.TLS_ALERT.ILLEGAL_PARAMETER); // fatal, illegal_parameter (47)
+          ev.emit('error', new Error('TLS downgrade attack detected (RFC 8446 §4.1.3 sentinel present)'));
+          return;
+        }
+      }
+
       // Server: TLS 1.2 resumption detection (only makes sense from ClientHello).
       // This runs BEFORE set_context's reactive loop picks a version, so we mark state
       // but defer the decision. The reactive loop will check tls12_abbreviated once
@@ -763,6 +806,26 @@ function TLSSession(options){
 
       pushTranscript(data);
 
+      // TLS 1.3: most server extensions arrive HERE, not in the
+      // ServerHello (RFC 8446 §4.3.1) — including application-protocol
+      // ones like use_srtp (RFC 8842 requires it in EncryptedExtensions).
+      // Merge them into remote_extensions so getRemoteExtension() sees a
+      // version-agnostic union: ServerHello entries first (kept on type
+      // collision, which the RFC forbids anyway), then EE entries.
+      if (Array.isArray(message.extensions) && message.extensions.length > 0) {
+        var _mergedExts = (context.remote_extensions || []).slice();
+        for (var _eei = 0; _eei < message.extensions.length; _eei++) {
+          var _ee = message.extensions[_eei];
+          if (!_ee) continue;
+          var _dup = false;
+          for (var _mj = 0; _mj < _mergedExts.length; _mj++) {
+            if (_mergedExts[_mj] && _mergedExts[_mj].type === _ee.type) { _dup = true; break; }
+          }
+          if (!_dup) _mergedExts.push(_ee);
+        }
+        context.remote_extensions = _mergedExts;
+      }
+
       set_context({
         remote_supported_groups: message.supported_groups || [],
       });
@@ -1187,6 +1250,12 @@ function TLSSession(options){
         }
       }
 
+      if('exporter_master_secret' in options){
+        if(context.exporter_master_secret==null && options.exporter_master_secret!==null){
+          context.exporter_master_secret=options.exporter_master_secret;
+        }
+      }
+
       if('tls13_master_secret' in options){
         if(context.tls13_master_secret==null && options.tls13_master_secret!==null){
           context.tls13_master_secret=options.tls13_master_secret;
@@ -1586,6 +1655,20 @@ function TLSSession(options){
 
           if(context.local_random==null){
             context.local_random=new Uint8Array(crypto.randomBytes(32));
+
+            // RFC 8446 §4.1.3: if we support TLS 1.3 but negotiated something
+            // lower, stamp the downgrade sentinel into the last 8 bytes of the
+            // ServerHello random so a 1.3-capable client can detect the downgrade.
+            // Only meaningful for a real ServerHello (not HRR, which reuses the
+            // magic HRR random), and only for the TLS transport (not DTLS here).
+            if (context.local_supported_versions.indexOf(wire.TLS_VERSION.TLS1_3) >= 0) {
+              if (context.selected_version === wire.TLS_VERSION.TLS1_2) {
+                context.local_random.set(DOWNGRADE_SENTINEL_TLS12, 24);
+              } else if (context.selected_version === wire.TLS_VERSION.TLS1_1 ||
+                         context.selected_version === wire.TLS_VERSION.TLS1_0) {
+                context.local_random.set(DOWNGRADE_SENTINEL_TLS11, 24);
+              }
+            }
           }
 
           let build_message_params=null;
@@ -1650,6 +1733,19 @@ function TLSSession(options){
               ext_list.push({ type: 'SESSION_TICKET', value: new Uint8Array(0) });
             }
 
+            // Custom local extensions (generic pass-through — same mechanism
+            // as the ClientHello and TLS 1.3 EncryptedExtensions paths).
+            // This is where server-side answers to client-offered extensions
+            // (e.g. use_srtp for DTLS-SRTP, RFC 5764 §4.1) go on the wire in
+            // (D)TLS 1.2. Previously local_extensions were silently dropped
+            // for the 1.2 ServerHello, so a server could never answer them.
+            // Responsibility for only answering extensions the client
+            // actually offered stays with the caller (it can inspect the
+            // ClientHello via the 'clienthello' event / getRemoteExtension).
+            for (let lei = 0; lei < context.local_extensions.length; lei++) {
+              ext_list.push(context.local_extensions[lei]);
+            }
+
             // Session ID: for abbreviated (resumed) handshake, MUST echo client's session_id
             // (RFC 5077 §3.4). For TLS 1.2 full handshake, generate a fresh 32-byte session_id
             // (matches OpenSSL/Node.js behavior for middlebox compatibility).
@@ -2367,10 +2463,18 @@ function TLSSession(options){
           if((context.isServer==true && context.finished_sent==true && context.remote_finished_ok==false) || (context.isServer==false && context.finished_sent==false && context.remote_finished_ok==true)){
 
             let appHashName = TLS_CIPHER_SUITES[context.selected_cipher_suite].hash;
-            let result2 = derive_app_traffic_secrets_with_hash(appHashName, context.base_secret, get_transcript_hash(appHashName));
+            let appTranscriptHash = get_transcript_hash(appHashName);
+            let result2 = derive_app_traffic_secrets_with_hash(appHashName, context.base_secret, appTranscriptHash);
 
             // Save master_secret for resumption before clearing
             params_to_set['tls13_master_secret'] = result2.master_secret;
+
+            // RFC 8446 §7.1: exporter_master_secret uses the SAME transcript
+            // hash (ClientHello..server Finished) as the app traffic secrets.
+            // Kept for the lifetime of the connection so exportKeyingMaterial
+            // (RFC 8446 §7.5) works after handshake completion.
+            params_to_set['exporter_master_secret'] =
+              derive_exporter_master_secret_with_hash(appHashName, result2.master_secret, appTranscriptHash);
             params_to_set['base_secret']=null;
 
             if (context.isServer === true) {
@@ -2426,7 +2530,9 @@ function TLSSession(options){
       //compare finished to expected...
       if(context.remote_finished_ok==false && context.remote_finished!==null && context.expected_remote_finished!==null){
 
-        if(uint8Equal(context.remote_finished, context.expected_remote_finished)==true){
+        // Constant-time Finished comparison — verify_data is a MAC; a timing
+        // oracle here would let a peer forge a valid Finished byte by byte.
+        if(timingSafeEqualU8(context.remote_finished, context.expected_remote_finished)==true){
 
           let message_data = build_tls_message({
             type: 'finished',
@@ -2761,27 +2867,45 @@ function TLSSession(options){
           ];
       context.local_supported_signature_algorithms = ch_sigalgs; // for CH2 reuse
 
-      let extensions = [
-        { 
-          type: 'SUPPORTED_VERSIONS', 
+      // supported_versions (43) and key_share (51) are the TLS 1.3
+      // negotiation machinery (RFC 8446 §4.1.2, §4.2.8). Offer them only
+      // when 1.3 is actually in the offered version set — a pure 1.2
+      // hello must look like a 1.2 hello, exactly as OpenSSL/BoringSSL
+      // behave with max_version=1.2. Previously both were emitted
+      // unconditionally, so even a maxVersion:'DTLSv1.2' profile (the
+      // WebRTC default) advertised a single-entry supported_versions and
+      // a dangling key_share: spec-legal (receivers MUST ignore unknown
+      // extensions, RFC 5246 §7.4.1.4) but non-canonical — and fatal to
+      // at least one deployed stack (webrtc-dtls ≤0.7 hard-errors on any
+      // extension outside its known set, then poisons its replay window
+      // so no retransmission can ever recover the handshake).
+      let offers13 = context.local_supported_versions.some(function (v) {
+        return v === wire.TLS_VERSION.TLS1_3 || v === wire.DTLS_VERSION.DTLS1_3;
+      });
+      let extensions = [];
+      if (offers13) {
+        extensions.push({
+          type: 'SUPPORTED_VERSIONS',
           value: context.local_supported_versions
-        },
-        {
-          type: 'SUPPORTED_GROUPS', 
-          value: context.local_supported_groups
-        },
-        {
-          type: 'KEY_SHARE', 
+        });
+      }
+      extensions.push({
+        type: 'SUPPORTED_GROUPS',
+        value: context.local_supported_groups
+      });
+      if (offers13) {
+        extensions.push({
+          type: 'KEY_SHARE',
           value: [{
-            group: 0x001d, 
-            key_exchange: public_key 
+            group: 0x001d,
+            key_exchange: public_key
           }]
-        },
-        {
-          type: 'SIGNATURE_ALGORITHMS', 
-          value: ch_sigalgs
-        }
-      ];
+        });
+      }
+      extensions.push({
+        type: 'SIGNATURE_ALGORITHMS',
+        value: ch_sigalgs
+      });
       if (!tls13Only) {
         // TLS 1.2 compatibility — meaningless (and suspicious to strict
         // stacks) in a 1.3-only/QUIC hello
@@ -3070,12 +3194,80 @@ function TLSSession(options){
       };
     },
 
+    /**
+     * Export keying material (RFC 5705 for TLS 1.2, RFC 8446 §7.5 for
+     * TLS 1.3). Mirrors Node's tls.TLSSocket#exportKeyingMaterial.
+     *
+     * DTLS-SRTP (RFC 5764) usage:
+     *   session.exportKeyingMaterial(len, 'EXTRACTOR-dtls_srtp')
+     * with NO context argument. Note the TLS 1.2 subtlety: "no context"
+     * and "empty context" produce different output — omit the argument
+     * (or pass null) for the RFC 5764 form.
+     *
+     * Returns a Buffer of `length` bytes, or null before the secrets
+     * are available (handshake not far enough along).
+     *
+     * NOTE: the previous implementation was TLS 1.3-only AND derived from
+     * the app traffic secret in a single HKDF stage — which is not the
+     * RFC 8446 §7.5 construction and would not interoperate with
+     * OpenSSL/BoringSSL exporters. Both issues are fixed here; if anything
+     * consumed the old output, its derived values will change.
+     *
+     * @param {number} length
+     * @param {string} label
+     * @param {Uint8Array|Buffer|null} [context_value]
+     * @returns {Buffer|null}
+     */
     exportKeyingMaterial: function(length, label, context_value){
-      if (!context.local_app_traffic_secret || !context.selected_cipher_suite) return new Uint8Array(0);
-      let hashName = TLS_CIPHER_SUITES[context.selected_cipher_suite].hash;
-      let hashFn = getHashFn(hashName);
-      let ctx_hash = hashFn(context_value || new Uint8Array(0));
-      return hkdf_expand_label(hashName, context.local_app_traffic_secret, label || 'exporter', ctx_hash, length || 32);
+      if (!context.selected_cipher_suite || !length || !label) return null;
+      var suite = TLS_CIPHER_SUITES[context.selected_cipher_suite];
+      if (!suite) return null;
+      var is13 = (context.selected_version === wire.TLS_VERSION.TLS1_3 ||
+                  context.selected_version === wire.DTLS_VERSION.DTLS1_3);
+
+      if (is13) {
+        // RFC 8446 §7.5 — two-stage derivation from exporter_master_secret.
+        if (!context.exporter_master_secret) return null;
+        return Buffer.from(tls13_exporter(
+          suite.hash, context.exporter_master_secret, label,
+          (context_value != null) ? context_value : null, length
+        ));
+      }
+
+      // TLS 1.2 — RFC 5705 over the master secret + hello randoms.
+      // client_random comes first in the seed regardless of our role.
+      if (!context.base_secret || !context.local_random || !context.remote_random) return null;
+      var clientRandom = context.isServer ? context.remote_random : context.local_random;
+      var serverRandom = context.isServer ? context.local_random  : context.remote_random;
+      return Buffer.from(tls12_exporter(
+        suite.hash, context.base_secret, label,
+        clientRandom, serverRandom,
+        (context_value != null) ? context_value : null, length
+      ));
+    },
+
+    /**
+     * All extensions the peer sent in its hello (ClientHello when we're
+     * the server, ServerHello when we're the client), as parsed by
+     * wire.parse_extensions: [{ type, name, data, value }].
+     * `data` is the raw extension payload (Uint8Array); `value` is the
+     * decoded form for known extensions, null for unknown ones.
+     */
+    getRemoteExtensions: function(){
+      return context.remote_extensions ? context.remote_extensions.slice() : [];
+    },
+
+    /**
+     * Look up a single peer extension by its numeric type
+     * (e.g. 14 = use_srtp, 0x39 = QUIC transport parameters).
+     * Returns the { type, name, data, value } entry, or null.
+     */
+    getRemoteExtension: function(type){
+      var list = context.remote_extensions || [];
+      for (var i = 0; i < list.length; i++) {
+        if (list[i] && list[i].type === type) return list[i];
+      }
+      return null;
     },
 
     /** Returns the local Finished verify_data (Buffer), or null. */