lemon-tls 0.6.0 → 0.9.0

package/src/utils.js

@@ -54,7 +54,13 @@ function arraysEqual(a, b) {
         return false;
       }
     }else{
-      if(typeof a[i]=='string' && typeof b[i]=='string'){
+      // Either element may be null/undefined here: the branch above requires
+      // BOTH to be non-null typed arrays, so a null slips through to this
+      // side and the `.constructor` reads below threw a TypeError. Settle
+      // those cases by identity before anything is dereferenced.
+      if(a[i]==null || b[i]==null){
+        if(a[i]!==b[i]) return false;
+      }else if(typeof a[i]=='string' && typeof b[i]=='string'){
         if (a[i] !== b[i]){
           return false;
         }
@@ -119,10 +125,77 @@ function timingSafeEqualU8(a, b) {
 }
 
 
+/**
+ * Parse an X509Certificate DN string into the object shape Node's certificate
+ * objects use.
+ *
+ * crypto.X509Certificate gives `subject`/`issuer` as newline-separated
+ * "KEY=value" text, but Node documents them on a certificate object as objects
+ * keyed by RDN type: { C, ST, L, O, OU, CN }. Passing the raw string through
+ * meant tls.checkServerIdentity() — which reads cert.subject.CN — could never
+ * find a Common Name, so any certificate without a SAN was rejected outright
+ * even when its CN matched. The exported identity check did not work against
+ * this library's own getPeerCertificate() output, which is exactly the pairing
+ * Node documents.
+ *
+ * A type may legitimately repeat (OU is the common case); Node represents a
+ * repeat as an array and a single occurrence as a plain string.
+ *
+ * Idempotent: an already-parsed object is returned unchanged, so callers can
+ * pass either form.
+ */
+function parseDN(dn) {
+  if (dn == null) return {};
+  if (typeof dn === 'object') return dn;
+  let out = {};
+  let lines = String(dn).split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    let line = lines[i];
+    if (!line) continue;
+    let eq = line.indexOf('=');
+    if (eq < 1) continue;
+    let k = line.slice(0, eq).trim();
+    let v = line.slice(eq + 1);
+    if (!Object.prototype.hasOwnProperty.call(out, k)) out[k] = v;
+    else if (Array.isArray(out[k])) out[k].push(v);
+    else out[k] = [out[k], v];
+  }
+  return out;
+}
+
+/**
+ * A certificate (DER) as node:tls's getPeerCertificate() describes it:
+ * subject and issuer as RDN objects, the SAN string, the validity dates,
+ * fingerprints, serial, and the raw DER. One place for TLSSocket, the
+ * session's identity check and anything above (QUIC) — they built it
+ * apiece. Unparseable: just { raw }.
+ */
+function certificateObject(der) {
+  if (!der) return null;
+  try {
+    let x = new crypto.X509Certificate(der);
+    return {
+      subject: parseDN(x.subject),
+      issuer: parseDN(x.issuer),
+      subjectaltname: x.subjectAltName,
+      valid_from: x.validFrom,
+      valid_to: x.validTo,
+      fingerprint: x.fingerprint,
+      fingerprint256: x.fingerprint256,
+      serialNumber: x.serialNumber,
+      raw: der
+    };
+  } catch (e) {
+    return { raw: der };
+  }
+}
+
 export {
+  certificateObject,
   concatUint8Arrays,
   arraybufferEqual,
   arraysEqual,
   uint8Equal,
-  timingSafeEqualU8
+  timingSafeEqualU8,
+  parseDN
 };

package/src/wire.js

@@ -17,6 +17,36 @@ const DTLS_VERSION = {
   DTLS1_3: 0xFEFC
 };
 
+/**
+ * Does `v` denote the TLS 1.3 *message* format?
+ *
+ * SINGLE SOURCE OF TRUTH for every "is this 1.3?" branch in this file.
+ * The reason it has to exist: DTLS 1.3 is TLS 1.3 at the message layer, but
+ * its version constant is 0xFEFC, not 0x0304. Every `v === TLS_VERSION.TLS1_3`
+ * comparison is therefore silently FALSE for DTLS 1.3, and silently selects
+ * the legacy TLS 1.2 encoding of whatever message is being built.
+ *
+ * That is not hypothetical: build_certificate below did exactly this, so a
+ * DTLS 1.3 server emitted a TLS 1.2 Certificate (no certificate_request_context,
+ * no per-entry extensions vector). The peer parsed byte 0 as the context length
+ * — which happened to be 0x00 and so passed — then read the next three bytes as
+ * certificate_list length and got a value far past the end of the message.
+ * BoringSSL answers that with decode_error(50).
+ *
+ * It only ever bit the server role, because the client-side Certificate call
+ * sites hardcode TLS_VERSION.TLS1_3 instead of passing the negotiated version.
+ * Two copies of this library also agree with each other, because
+ * parse_certificate sniffs both encodings — so only a conforming peer objects.
+ */
+function is_tls13_wire(v) {
+  return v === TLS_VERSION.TLS1_3 || v === DTLS_VERSION.DTLS1_3;
+}
+
+/** Companion to is_tls13_wire for the 1.2 message format. */
+function is_tls12_wire(v) {
+  return v === TLS_VERSION.TLS1_2 || v === DTLS_VERSION.DTLS1_2;
+}
+
 const TLS_CONTENT_TYPE = {
   CHANGE_CIPHER_SPEC: 20,
   ALERT: 21,
@@ -24,6 +54,14 @@ const TLS_CONTENT_TYPE = {
   APPLICATION_DATA: 23
 };
 
+// The largest one handshake message may be, as its header declares it, or a
+// CompressedCertificate decompressed to. OpenSSL allows a ClientHello of
+// 128 KB and certificate chains up to 100 KB (max_cert_list); QUIC's CRYPTO
+// buffer in QUICO is 64 KB. The 24-bit length would allow 16 MB — memory a
+// peer could make us hold, or inflate a few hundred bytes into, before it
+// has proven anything. A maxHandshakeSize below it lowers it.
+const HANDSHAKE_MESSAGE_MAX = 128 * 1024;
+
 const TLS_ALERT_LEVEL = {
   WARNING: 1,
   FATAL: 2
@@ -45,12 +83,14 @@ const TLS_ALERT = {
   PROTOCOL_VERSION: 70,
   INSUFFICIENT_SECURITY: 71,
   INTERNAL_ERROR: 80,
+  INAPPROPRIATE_FALLBACK: 86,   // RFC 7507 (TLS_FALLBACK_SCSV)
   USER_CANCELED: 90,
   MISSING_EXTENSION: 109,
   UNSUPPORTED_EXTENSION: 110,
   UNRECOGNIZED_NAME: 112,
   CERTIFICATE_REQUIRED: 116,
-  NO_APPLICATION_PROTOCOL: 120
+  NO_APPLICATION_PROTOCOL: 120,
+  ECH_REQUIRED: 121
 };
 
 const TLS_MESSAGE_TYPE = {
@@ -67,6 +107,8 @@ const TLS_MESSAGE_TYPE = {
   CLIENT_KEY_EXCHANGE: 16,
   FINISHED: 20,
   KEY_UPDATE: 24,
+  CERTIFICATE_STATUS: 22,       // RFC 6066 §8 (TLS 1.2: the stapled OCSP response)
+  COMPRESSED_CERTIFICATE: 25,   // RFC 8879
   MESSAGE_HASH: 254 // HRR flow marker
 };
 
@@ -83,6 +125,7 @@ const TLS_EXT = {
   MAX_FRAGMENT_LENGTH: 1,
   STATUS_REQUEST: 5,
   SUPPORTED_GROUPS: 10,
+  EC_POINT_FORMATS: 11,
   SIGNATURE_ALGORITHMS: 13,
   USE_SRTP: 14,
   HEARTBEAT: 15,
@@ -92,6 +135,7 @@ const TLS_EXT = {
   SERVER_CERT_TYPE: 20,
   PADDING: 21,
   EXTENDED_MASTER_SECRET: 23,
+  COMPRESS_CERTIFICATE: 27,     // RFC 8879
   SESSION_TICKET: 35,
   PRE_SHARED_KEY: 41,
   EARLY_DATA: 42,
@@ -146,6 +190,25 @@ function w_u48(buf, off, v) {
   return off;
 }
 
+/**
+ * 64-bit big-endian write. Split into two 32-bit halves rather than using
+ * BigInt: DTLS epochs and sequence numbers are both far below 2^53, so Number
+ * arithmetic is exact here and roughly an order of magnitude faster.
+ */
+function w_u64(buf, off, v) {
+  let hi = Math.floor(v / 0x100000000);
+  let lo = v >>> 0;
+  buf[off++] = (hi >>> 24) & 0xFF;
+  buf[off++] = (hi >>> 16) & 0xFF;
+  buf[off++] = (hi >>>  8) & 0xFF;
+  buf[off++] = (hi       ) & 0xFF;
+  buf[off++] = (lo >>> 24) & 0xFF;
+  buf[off++] = (lo >>> 16) & 0xFF;
+  buf[off++] = (lo >>>  8) & 0xFF;
+  buf[off++] = (lo       ) & 0xFF;
+  return off;
+}
+
 function w_bytes(buf, off, b) {
   buf.set(b, off);
   return off + b.length;
@@ -255,6 +318,7 @@ let exts = {};
 exts.SERVER_NAME = { encode: null, decode: null };
 exts.SUPPORTED_VERSIONS = { encode: null, decode: null };
 exts.SUPPORTED_GROUPS = { encode: null, decode: null };
+exts.EC_POINT_FORMATS = { encode: null, decode: null };
 exts.SIGNATURE_ALGORITHMS = { encode: null, decode: null };
 exts.PSK_KEY_EXCHANGE_MODES = { encode: null, decode: null };
 exts.KEY_SHARE = { encode: null, decode: null };
@@ -264,6 +328,47 @@ exts.RENEGOTIATION_INFO = { encode: null, decode: null };
 exts.SESSION_TICKET = { encode: null, decode: null };
 exts.EXTENDED_MASTER_SECRET = { encode: null, decode: null };
 exts.CERTIFICATE_AUTHORITIES = { encode: null, decode: null };
+exts.COMPRESS_CERTIFICATE = { encode: null, decode: null };
+exts.STATUS_REQUEST = { encode: null, decode: null };
+
+/* ---------------------- STATUS_REQUEST (5) ---------------------- */
+// RFC 6066 §8. Three places, three bodies:
+//   ClientHello:       CertificateStatusRequest — status_type ocsp(1),
+//                      responder_id_list<0..2^16-1>, request_extensions<0..2^16-1>
+//   ServerHello (1.2): empty — "a CertificateStatus message follows"
+//   CertificateEntry (1.3, RFC 8446 §4.4.2.1): CertificateStatus itself
+// Encoded from { ocsp: true } (the request with empty lists, as every
+// browser sends it) or a raw body; decoded to { status_type } or {} when
+// empty. Unknown status types are not an error: the server just does not
+// answer them.
+exts.STATUS_REQUEST.encode = function (value) {
+  if (value instanceof Uint8Array) return value;
+  if (value && value.ocsp) return new Uint8Array([1, 0, 0, 0, 0]);
+  return new Uint8Array(0);
+};
+exts.STATUS_REQUEST.decode = function (data) {
+  if (data.length === 0) return {};
+  return { status_type: data[0] };
+};
+
+/* ---------------------- COMPRESS_CERTIFICATE (27) ---------------------- */
+// RFC 8879 §3: CertificateCompressionAlgorithm algorithms<2..2^8-2> — a
+// one-byte length, then 16-bit codes.
+exts.COMPRESS_CERTIFICATE.encode = function (value) {
+  let list = Array.isArray(value) ? value : [];
+  let out = new Uint8Array(1 + list.length * 2);
+  out[0] = list.length * 2;
+  for (let i = 0; i < list.length; i++) w_u16(out, 1 + i * 2, list[i]);
+  return out;
+};
+exts.COMPRESS_CERTIFICATE.decode = function (data) {
+  if (data.length < 1) throw parseError('compress_certificate: empty');
+  let n = data[0];
+  if (n < 2 || n % 2 !== 0 || 1 + n !== data.length) throw parseError('compress_certificate: bad length');
+  let out = [];
+  for (let i = 1; i < 1 + n; i += 2) out.push((data[i] << 8) | data[i + 1]);
+  return out;
+};
 
 /* ---------------------- CERTIFICATE_AUTHORITIES (47) ---------------------- */
 // RFC 8446 §4.2.4: DistinguishedName authorities<3..2^16-1> — the list is
@@ -478,6 +583,24 @@ exts.SUPPORTED_GROUPS.decode = function (data) {
   return out; // array of named groups
 };
 
+/* ---------------------------- EC_POINT_FORMATS (11) ---------------------------- */
+// RFC 8422 §5.1.2: ECPointFormat ec_point_format_list<1..2^8-1>, one byte per
+// format. 0 is uncompressed — the only format TLS 1.2 still uses, and the one
+// every list must contain.
+exts.EC_POINT_FORMATS.encode = function (value) {
+  let formats = Array.isArray(value) && value.length > 0 ? value : [0];
+  return veclen(1, new Uint8Array(formats));
+};
+
+exts.EC_POINT_FORMATS.decode = function (data) {
+  let off = 0;
+  let list;
+  [list, off] = readVec(data, off, 1);
+  if (off !== data.length) throw parseError('trailing data after ec_point_formats');
+  if (list.length === 0) throw parseError('empty ec_point_formats list');
+  return Array.from(list); // array of point formats
+};
+
 /* -------------------------- SIGNATURE_ALGORITHMS (13) -------------------------- */
 exts.SIGNATURE_ALGORITHMS.encode = function (value) {
   // A codec encodes what it is handed; the set of signature schemes is policy
@@ -674,7 +797,16 @@ exts.KEY_SHARE.encode = function (value) {
   return veclen(2, concatUint8Arrays(parts));
 };
 
-exts.KEY_SHARE.decode = function (data) {
+// `kind` — the message the extension is in ('client_hello', 'server_hello';
+// parse_hello passes it) — decides the form; the three forms cannot be told
+// apart by length. An empty client_shares, which RFC 8446 §4.2.8 allows ("in
+// order to request group selection from the server, at the cost of an
+// additional round trip"), is two bytes [00 00]: read as a HelloRetryRequest's
+// NamedGroup it became a share for group 0x0000, refused illegal_parameter
+// (not in supported_groups) — where the client asked for a HelloRetryRequest.
+// Scanners enumerate a server's groups exactly so; every probe failed.
+exts.KEY_SHARE.decode = function (data, kind) {
+  if (kind === 'client_hello') return decode_client_shares(data);
   // HelloRetryRequest form: just NamedGroup (2 bytes, no key_exchange)
   if (data.length === 2) {
     let g, off = 0;
@@ -698,12 +830,17 @@ exts.KEY_SHARE.decode = function (data) {
     }
   }
 
-  // ClientHello form: vector<2> of KeyShareEntry
+  return decode_client_shares(data);
+};
+
+// ClientHello form: vector<2> of KeyShareEntry, exactly filling the extension.
+function decode_client_shares(data) {
   let off2 = 0;
   let listBytes;
   [listBytes, off2] = r_u16(data, off2);
 
   let end = off2 + listBytes;
+  if (end !== data.length) throw parseError('key_share: client_shares length does not match the extension');
   let out = [];
 
   while (off2 < end) {
@@ -718,9 +855,10 @@ exts.KEY_SHARE.decode = function (data) {
 
     out.push({ group: g2, key_exchange: ke2 });
   }
+  if (off2 !== end) throw parseError('key_share: an entry overruns client_shares');
 
   return out; // array of entries
-};
+}
 
 /* ------------------------------------ ALPN (16) ----------------------------------- */
 exts.ALPN.encode = function (value) {
@@ -900,7 +1038,7 @@ function build_extensions(list) {
  *     CertificateRequest) → use parse_extension_list().
  * Both share this core so the duplicate/overflow rules apply identically.
  */
-function parse_extension_list(buf) {
+function parse_extension_list(buf, kind) {
   let off = 0;
   let out = [];
   let seen = {};   // RFC 8446 §4.2: "There MUST NOT be more than one extension of the same type"
@@ -937,7 +1075,7 @@ function parse_extension_list(buf) {
 
     let name = ext_name_by_code(t);
     let dec = exts[name] && exts[name].decode;
-    let val = dec ? dec(d) : null;
+    let val = dec ? dec(d, kind) : null;
 
     out.push({ type: t, name: name, data: d, value: val });
   }
@@ -949,7 +1087,7 @@ function parse_extension_list(buf) {
  * Parse a length-prefixed extensions vector that ENDS the enclosing structure.
  * `buf` must START with the 2-byte vector length and contain nothing after it.
  */
-function parse_extensions(buf) {
+function parse_extensions(buf, kind) {
   let off = 0;
   let n;
   [n, off] = r_u16(buf, off);
@@ -961,7 +1099,7 @@ function parse_extensions(buf) {
   if (end > buf.length) throw parseError('extensions vector length exceeds body');
   if (end < buf.length) throw parseError('trailing data after extensions vector');
 
-  return parse_extension_list(buf.subarray(off, end));
+  return parse_extension_list(buf.subarray(off, end), kind);
 }
 
 
@@ -1109,7 +1247,7 @@ function parse_hello(params) {
   let extensions = [];
   if (body.length > off) {
     let extRaw = body.subarray(off);
-    extensions = parse_extensions(extRaw);
+    extensions = parse_extensions(extRaw, type);
   }
 
   // --- version תמיד ערך יחיד ---
@@ -1151,6 +1289,14 @@ function build_certificate(params) {
   // TLS 1.3 → מחזיר:  request_context (vec<1>) || certificate_list (vec<3> של [ cert(vec<3>) || extensions(vec<2>) ]*)
   // TLS 1.2 → מחזיר:  certificate_list (vec<3> של cert(vec<3>)*), מתעלם מ-extensions/request_context
 
+  // NOTE the asymmetry with build_certificate_request, which defaults to
+  // TLS1_3. Both defaults are kept as they were, because callers outside this
+  // file may rely on them; every call site inside the library passes `version`
+  // explicitly, so the default is never actually exercised here. What matters
+  // is that the branch below asks is_tls13_wire(v), not v === TLS1_3 — the
+  // mismatched defaults are what made the two messages in the SAME server
+  // flight come out in two different encodings, which is why this stayed
+  // hidden for so long.
   let v = params.version || TLS_VERSION.TLS1_2;
 
   // Normalize to entries[] always
@@ -1161,8 +1307,14 @@ function build_certificate(params) {
   }
   if (!entries) entries = [];
 
-  if (v === TLS_VERSION.TLS1_3) {
-    let ctx = toU8(params.request_context || new Uint8Array(0));
+  if (is_tls13_wire(v)) {
+    // Accept either spelling of the context field. build_tls_message callers
+    // pass `certificate_request_context` (the RFC 8446 field name); this
+    // builder originally read only `request_context`, so the value was
+    // dropped without a word. Harmless during the initial handshake, where
+    // the context is always empty — but post-handshake client authentication
+    // is identified BY that context, so it would have failed silently.
+    let ctx = toU8(params.request_context || params.certificate_request_context || new Uint8Array(0));
 
     let entryParts = [];
     for (let i = 0; i < entries.length; i++) {
@@ -1199,6 +1351,51 @@ function build_certificate(params) {
   }
 }
 
+/* ------------------------ CompressedCertificate ------------------------ */
+// RFC 8879 §4: algorithm (u16), uncompressed_length (u24),
+// compressed_certificate_message<1..2^24-1> (u24-prefixed).
+/**
+ * CertificateStatus (RFC 6066 §8): status_type ocsp(1), then the DER OCSP
+ * response as an opaque<1..2^24-1>. The body of the TLS 1.2 handshake
+ * message, and of the status_request extension in a TLS 1.3 CertificateEntry.
+ */
+function build_certificate_status(response) {
+  let r = toU8(response);
+  let out = new Uint8Array(4 + r.length);
+  out[0] = 1;
+  out[1] = (r.length >>> 16) & 0xff; out[2] = (r.length >>> 8) & 0xff; out[3] = r.length & 0xff;
+  out.set(r, 4);
+  return out;
+}
+
+/** CertificateStatus → { status_type, response }; decode_error on a bad length. */
+function parse_certificate_status(body) {
+  if (body.length < 4) throw parseError('CertificateStatus: too short');
+  let len = (body[1] << 16) | (body[2] << 8) | body[3];
+  if (len === 0 || 4 + len !== body.length) throw parseError('CertificateStatus: bad length');
+  return { status_type: body[0], response: body.slice(4) };
+}
+
+function build_compressed_certificate(params) {
+  let data = params.compressed;
+  let out = new Uint8Array(2 + 3 + 3 + data.length);
+  let o = 0;
+  o = w_u16(out, o, params.algorithm);
+  out[o++] = (params.uncompressed_length >>> 16) & 0xff; out[o++] = (params.uncompressed_length >>> 8) & 0xff; out[o++] = params.uncompressed_length & 0xff;
+  out[o++] = (data.length >>> 16) & 0xff; out[o++] = (data.length >>> 8) & 0xff; out[o++] = data.length & 0xff;
+  out.set(data, o);
+  return out;
+}
+
+function parse_compressed_certificate(body) {
+  if (body.length < 8) throw parseError('CompressedCertificate: truncated');
+  let algorithm = (body[0] << 8) | body[1];
+  let uncompressed_length = (body[2] << 16) | (body[3] << 8) | body[4];
+  let n = (body[5] << 16) | (body[6] << 8) | body[7];
+  if (n < 1 || 8 + n !== body.length) throw parseError('CompressedCertificate: bad length');
+  return { algorithm: algorithm, uncompressed_length: uncompressed_length, compressed: body.subarray(8) };
+}
+
 function parse_certificate(body) {
   // always returns:
   // {
@@ -1400,8 +1597,10 @@ function parse_new_session_ticket(body) {
 function build_certificate_request(params) {
   let v = params && params.version || TLS_VERSION.TLS1_3;
 
-  if (v === TLS_VERSION.TLS1_3) {
-    let ctx = toU8((params && params.request_context) || new Uint8Array(0));
+  if (is_tls13_wire(v)) {
+    // Same dual-spelling accommodation as build_certificate above.
+    let ctx = toU8((params && (params.request_context || params.certificate_request_context)) ||
+                   new Uint8Array(0));
 
     // RFC 8446 §4.3.2: "The 'signature_algorithms' extension MUST be specified"
     // in a TLS 1.3 CertificateRequest.
@@ -1867,8 +2066,11 @@ function parse_hello_verify_request(body) {
 
 /* ================================ Exports ================================= */
 export {
+  HANDSHAKE_MESSAGE_MAX,
   TLS_VERSION,
   DTLS_VERSION,
+  is_tls13_wire,
+  is_tls12_wire,
   TLS_CONTENT_TYPE,
   TLS_ALERT_LEVEL,
   TLS_ALERT,
@@ -1879,6 +2081,7 @@ export {
   w_u16,
   w_u24,
   w_u48,
+  w_u64,
   w_bytes,
   r_u8,
   r_u16,
@@ -1899,6 +2102,10 @@ export {
 
   build_certificate,
   parse_certificate,
+  build_compressed_certificate,
+  parse_compressed_certificate,
+  build_certificate_status,
+  parse_certificate_status,
 
   build_certificate_verify,
   parse_certificate_verify,