lemon-tls 0.4.1 → 0.5.0

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',
@@ -3070,12 +3176,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. */

package/src/tls_socket.js

@@ -331,6 +331,18 @@ function TLSSocket(duplex, options){
             ? context.isTls13
             : session.getVersion() === 0x0304; // early records (pre-secureConnect)
 
+        // AEAD decryption can throw on any forged/corrupted record (GCM/ChaCha
+        // tag mismatch surfaces as an exception from decipher.final()). Left
+        // unhandled, a single injected bad segment would throw out of the
+        // transport 'data' handler — an unhandled exception that tears down the
+        // connection or the process: a trivial remote DoS.
+        //
+        // RFC 8446 §5.2: in TLS (unlike DTLS, which silently drops), a record
+        // that fails to decrypt MUST be treated as a fatal error. So we catch,
+        // send a fatal bad_record_mac alert, destroy the connection, and stop.
+        // The read sequence number is intentionally NOT advanced on failure —
+        // the rejected record never counts.
+        try {
         if (!isTls13 && context.remote_ccs_seen === true) {
             // TLS 1.2: decrypt with key_block derived keys
             if (context.app_read_key === null) {
@@ -394,7 +406,14 @@ function TLSSocket(duplex, options){
             }
             context.handshake_read_seq++;
         }
-        
+        } catch (e) {
+            // Record failed authentication → fatal bad_record_mac (RFC 8446 §5.2).
+            try { session.sendAlert ? session.sendAlert(2, TLS_ALERT.BAD_RECORD_MAC) : null; } catch (_) {}
+            self.emit('error', new Error('TLS record decryption failed (bad_record_mac)'));
+            self.destroy();
+            return;
+        }
+
 
         if (out !== null) {
             // Reuse cached isTls13 computed at the top of this function
@@ -1427,6 +1446,30 @@ function TLSSocket(duplex, options){
     /** Full negotiation result — all selected parameters in one object. */
     self.getNegotiationResult = function(){ return session.getNegotiationResult ? session.getNegotiationResult() : null; };
 
+    /**
+     * Export keying material (RFC 5705 for TLS 1.2, RFC 8446 §7.5 for
+     * TLS 1.3). Mirrors Node's tls.TLSSocket#exportKeyingMaterial —
+     * same argument order (length, label, context). One deliberate
+     * difference: Node THROWS before the handshake completes; we return
+     * null (matching this library's null-until-ready convention used by
+     * getTrafficSecrets etc.).
+     */
+    self.exportKeyingMaterial = function(length, label, context_value){
+        return session.exportKeyingMaterial
+          ? session.exportKeyingMaterial(length, label, context_value)
+          : null;
+    };
+
+    /** Peer hello extensions: [{ type, name, data, value }]. */
+    self.getRemoteExtensions = function(){
+        return session.getRemoteExtensions ? session.getRemoteExtensions() : [];
+    };
+
+    /** One peer extension by numeric type, or null. */
+    self.getRemoteExtension = function(type){
+        return session.getRemoteExtension ? session.getRemoteExtension(type) : null;
+    };
+
     /** Request Key Update — refresh outgoing encryption keys (TLS 1.3 only). */
     self.rekeySend = function(){ if (session.requestKeyUpdate) session.requestKeyUpdate(false); };
 

package/src/utils.js

@@ -1,3 +1,4 @@
+import crypto from 'node:crypto';
 
 function concatUint8Arrays(arrays) {
     let totalLength = 0;
@@ -93,9 +94,35 @@ function uint8Equal(a, b) {
 }
 
 
+/**
+ * Constant-time equality for two byte arrays.
+ *
+ * Unlike uint8Equal (which short-circuits on the first differing byte and
+ * therefore leaks — via timing — how many leading bytes matched), this always
+ * compares the full length. Use it wherever a mismatch would otherwise be
+ * exploitable as an oracle: Finished verify_data, PSK binders, ticket key_name,
+ * and any MAC/tag comparison.
+ *
+ * Returns false immediately (and safely) on length mismatch — that's public
+ * information, not a secret, so short-circuiting there is fine.
+ *
+ * Note: crypto.timingSafeEqual requires two equal-length Buffers. We wrap the
+ * inputs as Buffer views over the same memory (no copy) via byteOffset/length.
+ */
+function timingSafeEqualU8(a, b) {
+  if (a == null || b == null) return false;
+  if (a.length !== b.length) return false;
+  if (a.length === 0) return true;
+  let ba = Buffer.isBuffer(a) ? a : Buffer.from(a.buffer, a.byteOffset, a.length);
+  let bb = Buffer.isBuffer(b) ? b : Buffer.from(b.buffer, b.byteOffset, b.length);
+  return crypto.timingSafeEqual(ba, bb);
+}
+
+
 export {
   concatUint8Arrays,
   arraybufferEqual,
   arraysEqual,
-  uint8Equal
+  uint8Equal,
+  timingSafeEqualU8
 };