lemon-tls 0.9.0 → 0.11.0

package/src/wire.js

@@ -42,6 +42,17 @@ function is_tls13_wire(v) {
   return v === TLS_VERSION.TLS1_3 || v === DTLS_VERSION.DTLS1_3;
 }
 
+/** A version's node:tls name ('TLSv1.3', 'DTLSv1.2' …), or null. */
+function version_name(v) {
+  switch (v) {
+    case TLS_VERSION.TLS1_3: return 'TLSv1.3';
+    case TLS_VERSION.TLS1_2: return 'TLSv1.2';
+    case DTLS_VERSION.DTLS1_3: return 'DTLSv1.3';
+    case DTLS_VERSION.DTLS1_2: return 'DTLSv1.2';
+  }
+  return null;
+}
+
 /** 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;
@@ -56,8 +67,8 @@ const TLS_CONTENT_TYPE = {
 
 // 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
+// 128 KB and certificate chains up to 100 KB (max_cert_list). 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;
@@ -74,6 +85,7 @@ const TLS_ALERT = {
   RECORD_OVERFLOW: 22,
   HANDSHAKE_FAILURE: 40,
   BAD_CERTIFICATE: 42,
+  UNSUPPORTED_CERTIFICATE: 43,
   CERTIFICATE_EXPIRED: 45,
   CERTIFICATE_UNKNOWN: 46,
   ILLEGAL_PARAMETER: 47,
@@ -87,6 +99,7 @@ const TLS_ALERT = {
   USER_CANCELED: 90,
   MISSING_EXTENSION: 109,
   UNSUPPORTED_EXTENSION: 110,
+  NO_RENEGOTIATION: 100,
   UNRECOGNIZED_NAME: 112,
   CERTIFICATE_REQUIRED: 116,
   NO_APPLICATION_PROTOCOL: 120,
@@ -99,6 +112,8 @@ const TLS_MESSAGE_TYPE = {
   NEW_SESSION_TICKET: 4,
   END_OF_EARLY_DATA: 5,
   ENCRYPTED_EXTENSIONS: 8,
+  REQUEST_CONNECTION_ID: 9,     // DTLS 1.3 (RFC 9147 §5.8.4)
+  NEW_CONNECTION_ID: 10,        // DTLS 1.3 (RFC 9147 §5.8.3)
   CERTIFICATE: 11,
   SERVER_KEY_EXCHANGE: 12,
   CERTIFICATE_REQUEST: 13,
@@ -136,6 +151,7 @@ const TLS_EXT = {
   PADDING: 21,
   EXTENDED_MASTER_SECRET: 23,
   COMPRESS_CERTIFICATE: 27,     // RFC 8879
+  RECORD_SIZE_LIMIT: 28,        // RFC 8449
   SESSION_TICKET: 35,
   PRE_SHARED_KEY: 41,
   EARLY_DATA: 42,
@@ -147,6 +163,7 @@ const TLS_EXT = {
   POST_HANDSHAKE_AUTH: 49,
   SIGNATURE_ALGORITHMS_CERT: 50,
   KEY_SHARE: 51,
+  CONNECTION_ID: 54,            // RFC 9146 (DTLS)
   RENEGOTIATION_INFO: 0xFF01
 };
 
@@ -295,6 +312,27 @@ function veclen(lenBytes, inner) {
   throw new Error('veclen only supports 1/2/3');
 }
 
+/**
+ * A list of fixed-size items — u8 or u16 each — in a vector that fills the
+ * extension exactly (RFC 8446 §3.4): declared length = what follows it, a
+ * whole number of items, at least `min` of them (the vector's floor:
+ * `<2..2^16-2>` is one u16 item). One reader for every such list, since each
+ * decoder had its own loop that read past the declared length, accepted an
+ * odd length, an empty list, or bytes after it.
+ */
+function readItemList(data, lenBytes, itemBytes, min, name) {
+  let n, off;
+  [n, off] = lenBytes === 1 ? r_u8(data, 0) : r_u16(data, 0);
+  if (off + n !== data.length) throw parseError(name + ': list of ' + n + ' bytes in an extension of ' + (data.length - off));
+  if (n % itemBytes !== 0) throw parseError(name + ': list of ' + n + ' bytes, not a whole number of items');
+  if (n / itemBytes < min) throw parseError(name + ': empty list');
+  let out = [];
+  for (let i = 0; i < n; i += itemBytes) {
+    out.push(itemBytes === 2 ? ((data[off + i] << 8) | data[off + i + 1]) >>> 0 : data[off + i]);
+  }
+  return out;
+}
+
 function readVec(buf, off, lenBytes) {
   let n, off2 = off;
 
@@ -346,8 +384,29 @@ exts.STATUS_REQUEST.encode = function (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 {};
+// RFC 6066 §8. In a ServerHello (TLS 1.2) the extension_data is empty: a
+// bare "a CertificateStatus follows". In a ClientHello, a
+// CertificateStatusRequest: status_type, then for ocsp(1) responder_id_list
+// <0..2^16-1> and request_extensions<0..2^16-1>, and nothing after them. Bytes
+// left over were taken as an offer all the same.
+exts.STATUS_REQUEST.decode = function (data, kind) {
+  if (kind === 'server_hello') {
+    if (data.length !== 0) throw parseError('status_request: ' + data.length + ' bytes in a ServerHello, which carries none');
+    return {};
+  }
+  // Elsewhere (a TLS 1.3 Certificate entry holds a CertificateStatus, read
+  // by parse_certificate_status; a CertificateRequest's is empty).
+  if (kind !== 'client_hello') return data.length === 0 ? {} : { status_type: data[0] };
+  if (data.length === 0) throw parseError('status_request: empty');
+  if (data[0] === 1) {
+    let off = 1;
+    for (let v = 0; v < 2; v++) {
+      if (off + 2 > data.length) throw parseError('status_request: truncated');
+      off += 2 + ((data[off] << 8) | data[off + 1]);
+      if (off > data.length) throw parseError('status_request: truncated');
+    }
+    if (off !== data.length) throw parseError('status_request: ' + (data.length - off) + ' trailing bytes');
+  }
   return { status_type: data[0] };
 };
 
@@ -484,12 +543,19 @@ exts.SERVER_NAME.decode = function (data) {
   // other half of the grammar.
   if (!data || data.length === 0) return null;
 
+  // From a client: server_name_list<1..2^16-1> filling the extension, each
+  // name non-empty (HostName<1..2^16-1>), at most one of each name_type
+  // (RFC 6066 §3). A list cut short, overrunning, with bytes after it, an
+  // empty host_name or two of them were all taken.
   let off = 0;
   let list;
   [list, off] = readVec(data, off, 2);
+  if (off !== data.length) throw parseError('server_name: bytes after the server_name_list');
+  if (list.length === 0) throw parseError('server_name: empty server_name_list');
 
   let off2 = 0;
   let host = "";
+  let seenTypes = {};
 
   while (off2 < list.length) {
     let typ;
@@ -501,7 +567,10 @@ exts.SERVER_NAME.decode = function (data) {
     let v;
     [v, off2] = r_bytes(list, off2, l);
 
+    if (seenTypes[typ]) throw parseError('server_name: two names of type ' + typ);
+    seenTypes[typ] = true;
     if (typ === 0) {
+      if (l === 0) throw parseError('server_name: empty host_name');
       host = (new TextDecoder()).decode(v);
     }
   }
@@ -533,26 +602,12 @@ exts.SUPPORTED_VERSIONS.encode = function (value) {
   return body;
 };
 
-exts.SUPPORTED_VERSIONS.decode = function (data) {
-  // ServerHello form: 2 bytes
-  if (data.length === 2) {
-    let v, off = 0;
-    [v, off] = r_u16(data, off);
-    return [v]; // return the selected version (number)
-  }
-
-  // ClientHello form: vector<1> of versions (u16 each)
-  let off2 = 0;
-  let n;
-  [n, off2] = r_u8(data, off2);
-
-  let out = [];
-  for (let i = 0; i < n; i += 2) {
-    let vv;
-    [vv, off2] = r_u16(data, off2);
-    out.push(vv);
-  }
-  return out; // return the array directly
+exts.SUPPORTED_VERSIONS.decode = function (data, kind) {
+  // ClientHello form: versions<2..254>, one u16 each.
+  if (kind === 'client_hello') return readItemList(data, 1, 2, 1, 'supported_versions');
+  // ServerHello / HelloRetryRequest form: selected_version, 2 bytes.
+  if (data.length !== 2) throw parseError('supported_versions: selected_version of ' + data.length + ' bytes');
+  return [((data[0] << 8) | data[1]) >>> 0];
 };
 
 /* ---------------------------- SUPPORTED_GROUPS (10) ---------------------------- */
@@ -570,17 +625,7 @@ exts.SUPPORTED_GROUPS.encode = function (value) {
 };
 
 exts.SUPPORTED_GROUPS.decode = function (data) {
-  let off = 0;
-  let n;
-  [n, off] = r_u16(data, off);
-
-  let out = [];
-  for (let i = 0; i < n; i += 2) {
-    let g;
-    [g, off] = r_u16(data, off);
-    out.push(g);
-  }
-  return out; // array of named groups
+  return readItemList(data, 2, 2, 1, 'supported_groups');   // named_group_list<2..2^16-1>
 };
 
 /* ---------------------------- EC_POINT_FORMATS (11) ---------------------------- */
@@ -624,17 +669,8 @@ exts.SIGNATURE_ALGORITHMS.encode = function (value) {
 };
 
 exts.SIGNATURE_ALGORITHMS.decode = function (data) {
-  let off = 0;
-  let n;
-  [n, off] = r_u16(data, off);
-
-  let out = [];
-  for (let i = 0; i < n; i += 2) {
-    let a;
-    [a, off] = r_u16(data, off);
-    out.push(a);
-  }
-  return out; // array of sigalgs (u16)
+  // supported_signature_algorithms<2..2^16-2>: an empty or odd list was taken.
+  return readItemList(data, 2, 2, 1, 'signature_algorithms');
 };
 
 /* ------------------------ PSK_KEY_EXCHANGE_MODES (45) ------------------------ */
@@ -652,17 +688,7 @@ exts.PSK_KEY_EXCHANGE_MODES.encode = function (value) {
 };
 
 exts.PSK_KEY_EXCHANGE_MODES.decode = function (data) {
-  let off = 0;
-  let n;
-  [n, off] = r_u8(data, off);
-
-  let out = [];
-  for (let i = 0; i < n; i++) {
-    let m;
-    [m, off] = r_u8(data, off);
-    out.push(m);
-  }
-  return out; // array of modes (u8)
+  return readItemList(data, 1, 1, 1, 'psk_key_exchange_modes');   // ke_modes<1..255>
 };
 
 /* ------------------------------- PRE_SHARED_KEY (41) ------------------------------- */
@@ -730,28 +756,37 @@ exts.PRE_SHARED_KEY.decode = function (data) {
     return { selected: sel };
   }
 
-  // ClientHello: identities + binders
+  // ClientHello: identities<7..2^16-1>, then binders<33..2^16-1>, which
+  // fill the rest exactly (RFC 8446 §4.2.11): PskIdentity is identity<1..>
+  // and a 4-byte age; PskBinderEntry<32..255>.
   let idLen;
   [idLen, off] = r_u16(data, off);
   let idEnd = off + idLen;
+  if (idEnd > data.length) throw parseError('pre_shared_key: identities overrun the extension');
   let identities = [];
   while (off < idEnd) {
     let idL;
     [idL, off] = r_u16(data, off);
+    if (idL === 0) throw parseError('pre_shared_key: empty identity');
+    if (off + idL + 4 > idEnd) throw parseError('pre_shared_key: an identity overruns the list');
     let identity;
     [identity, off] = r_bytes(data, off, idL);
     let age = (data[off] << 24) | (data[off+1] << 16) | (data[off+2] << 8) | data[off+3];
     off += 4;
     identities.push({ identity: identity, age: age >>> 0 });
   }
+  if (identities.length === 0) throw parseError('pre_shared_key: no identities');
 
   let binderLen;
   [binderLen, off] = r_u16(data, off);
   let binderEnd = off + binderLen;
+  if (binderEnd !== data.length) throw parseError('pre_shared_key: binders do not fill the extension');
   let binders = [];
   while (off < binderEnd) {
     let bL;
     [bL, off] = r_u8(data, off);
+    if (bL < 32) throw parseError('pre_shared_key: binder of ' + bL + ' bytes, fewer than 32');
+    if (off + bL > binderEnd) throw parseError('pre_shared_key: a binder overruns the list');
     let binder;
     [binder, off] = r_bytes(data, off, bL);
     binders.push(binder);
@@ -893,6 +928,7 @@ exts.ALPN.decode = function (data) {
   let end = off + n;
   if (end > data.length) throw parseError('ALPN list length exceeds extension body');
   if (end < data.length) throw parseError('trailing data after ALPN protocol list');
+  if (n === 0) throw parseError('ALPN: empty protocol_name_list');   // <2..2^16-1>
 
   let out = [];
 
@@ -927,6 +963,7 @@ exts.RENEGOTIATION_INFO.decode = function (data) {
   let off = 0;
   let v;
   [v, off] = readVec(data, off, 1);
+  if (off !== data.length) throw parseError('renegotiation_info: bytes after renegotiated_connection');
   return v; // return raw bytes (Uint8Array)
 };
 
@@ -940,6 +977,7 @@ exts.COOKIE.decode = function (data) {
   let off = 0;
   let v;
   [v, off] = readVec(data, off, 2);
+  if (off !== data.length || v.length === 0) throw parseError('cookie: not one non-empty cookie<1..2^16-1>');
   return v; // Uint8Array — opaque cookie
 };
 
@@ -962,6 +1000,8 @@ exts.EXTENDED_MASTER_SECRET.encode = function (value) {
 };
 
 exts.EXTENDED_MASTER_SECRET.decode = function (data) {
+  // "extension_data field ... is empty" (RFC 7627 §5.1).
+  if (data && data.length !== 0) throw parseError('extended_master_secret with ' + data.length + ' bytes of data');
   return true; // presence is the signal
 };
 /* ============================= Extensions helpers ============================= */
@@ -1201,15 +1241,21 @@ function parse_hello(params) {
   let legacy_version; [legacy_version, off] = r_u16(body, off);
   let random;         [random,         off] = r_bytes(body, off, 32);
   let sidLen;         [sidLen,         off] = r_u8(body, off);
+  // legacy_session_id<0..32> (RFC 8446 §4.1.2, RFC 5246 §7.4.1.2).
+  if (sidLen > 32) throw parseError('session_id of ' + sidLen + ' bytes, more than 32');
   let session_id;     [session_id,     off] = r_bytes(body, off, sidLen);
 
   let cipher_suites = [];
   let legacy_compression = [];
   let type = isClient ? 'client_hello' : 'server_hello';
 
-  // DTLS cookie — auto-detect by version (DTLS versions have 0xFE in high byte)
+  // DTLS or TLS: the transport's to say (params.dtls), not the hello's — a
+  // TLS ClientHello with legacy_version (254,254) was read as a DTLS one, a
+  // cookie field looked for where the cipher suites are: decode_error, for a
+  // hello that offers TLS 1.2. Guessed from the version only when the caller
+  // does not say.
   let dtls_cookie = null;
-  let isDTLS = (legacy_version & 0xFF00) === 0xFE00;
+  let isDTLS = (typeof params.dtls === 'boolean') ? params.dtls : (legacy_version & 0xFF00) === 0xFE00;
 
   if (isClient) {
     // --- ClientHello ---
@@ -1221,7 +1267,17 @@ function parse_hello(params) {
       }
     }
 
+    // cipher_suites<2..2^16-2> (RFC 8446 §4.1.2, RFC 5246 §7.4.1.2): never
+    // empty, whole suites only, inside the message. An empty list was taken
+    // (and the server, with nothing to choose, sent nothing); an odd length
+    // read a byte past it.
+    // (params.lenient: a hello read to be fingerprinted — JA4 has a form
+    // for an empty list — not to be answered.)
     let csLen; [csLen, off] = r_u16(body, off);
+    if (off + csLen > body.length || (!params.lenient && (csLen < 2 || (csLen & 1) !== 0))) {
+      throw parseError('ClientHello cipher_suites: length ' + csLen);
+    }
+    if (params.lenient) csLen -= csLen & 1;
     let csEnd = off + csLen;
     while (off < csEnd) {
       let cs; [cs, off] = r_u16(body, off);
@@ -1261,6 +1317,7 @@ function parse_hello(params) {
     random: random,                       // single (Uint8Array(32))
     session_id: session_id,               // single (Uint8Array)
     dtls_cookie: dtls_cookie,             // Uint8Array or null (DTLS only)
+    dtls: isDTLS,
     cipher_suites: cipher_suites,         // array
     legacy_compression: legacy_compression, // array
     extensions: extensions                // array
@@ -1396,73 +1453,49 @@ function parse_compressed_certificate(body) {
   return { algorithm: algorithm, uncompressed_length: uncompressed_length, compressed: body.subarray(8) };
 }
 
-function parse_certificate(body) {
-  // always returns:
-  // {
-  //   version: TLS_VERSION.TLS1_2 | TLS_VERSION.TLS1_3,
-  //   request_context?: Uint8Array,         // רק ב-1.3
-  //   entries: [ { cert: Uint8Array, extensions?: any[] } ]  // ב-1.2 אין extensions
-  // }
-
-  // Try to detect TLS 1.3: rc(vec<1>) ואז list(vec<3> של [cert(vec<3>) || exts(vec<2>)]*)
-  if (body && body.length >= 4) {
-    let off = 0;
-    let rcLen; [rcLen, off] = r_u8(body, off);              // 1 byte
-    const afterCtx = off + rcLen;                           // off מצביע אחרי rcLen (כלומר 1)
-    if (afterCtx + 3 <= body.length) {
-      let listLen, off2 = afterCtx;                         // התחלת certificate_list
-      [listLen, off2] = r_u24(body, off2);                  // 3 bytes
-      if (afterCtx + 3 + listLen === body.length) {
-        // looks like valid TLS 1.3
-        const request_context = body.subarray(off, off + rcLen);
-        off = off2;
-        const end = off2 + listLen;
-
-        const entries = [];
-        while (off < end) {
-          let certLen; [certLen, off] = r_u24(body, off);   // cert_data vec<3>
-          let cert;    [cert,    off] = r_bytes(body, off, certLen);
-
-          let extLen;  [extLen,  off] = r_u16(body, off);   // extensions vec<2>
-          let extRaw;  [extRaw,  off] = r_bytes(body, off, extLen);
-
-          // extRaw is the list body (prefix already consumed above), so use
-          // the list parser — parse_extensions() would misread the first two
-          // bytes of the first extension as a vector length.
-          const extensions = parse_extension_list(extRaw);
-          entries.push({ cert, extensions });
-        }
-
-        return {
-          version: TLS_VERSION.TLS1_3,
-          request_context,
-          entries
-        };
-      }
-    }
+/**
+ * A Certificate message's body, as the version negotiated has it:
+ *   TLS 1.3 (RFC 8446 §4.4.2): certificate_request_context<0..2^8-1>, then
+ *     certificate_list<0..2^24-1> of { cert_data<1..2^24-1>,
+ *     extensions<0..2^16-1> };
+ *   TLS 1.2 (RFC 5246 §7.4.2): certificate_list<0..2^24-1> of
+ *     ASN.1Cert<1..2^24-1>.
+ * Every length exact — the list ends the message, each entry inside the
+ * list — or decode_error.
+ *
+ * The version was guessed from the bytes: a body that read as 1.3 was
+ * taken as 1.3, and anything else as 1.2 with its list length unchecked
+ * ("graceful recovery") — a TLS 1.2 Certificate whose length was wrong was
+ * taken (tlsfuzzer). The session always knows which it negotiated.
+ *
+ * Returns { version, request_context? (1.3), entries: [{ cert,
+ * extensions? (1.3) }] }.
+ */
+function parse_certificate(body, tls13) {
+  let off = 0, request_context;
+  if (tls13) {
+    let rcLen; [rcLen, off] = r_u8(body, off);
+    [request_context, off] = r_bytes(body, off, rcLen);
   }
-
-  // otherwise: TLS 1.2 — certificate_list(vec<3>) של cert(vec<3>)* ללא הרחבות
-  let off3 = 0;
-  let listLen2; [listLen2, off3] = r_u24(body, off3);
-
-  const end2 = off3 + listLen2;
-  if (end2 !== body.length) {
-    // graceful recovery: אם האורך לא תואם, ננסה לפחות לא לקרוס (אפשר גם לזרוק שגיאה)
-    // throw new Error('Bad TLS1.2 Certificate length');
+  let listLen; [listLen, off] = r_u24(body, off);
+  if (off + listLen !== body.length) {
+    throw parseError('Certificate: certificate_list of ' + listLen + ' bytes in ' + (body.length - off));
   }
-
-  const entries12 = [];
-  while (off3 < Math.min(end2, body.length)) {
-    let len3; [len3, off3] = r_u24(body, off3);
-    let cert; [cert, off3] = r_bytes(body, off3, len3);
-    entries12.push({ cert }); // no per-entry extensions in 1.2
+  const entries = [];
+  while (off < body.length) {
+    let certLen; [certLen, off] = r_u24(body, off);
+    if (certLen === 0) throw parseError('Certificate: an empty certificate in the list');
+    let cert; [cert, off] = r_bytes(body, off, certLen);
+    if (!tls13) { entries.push({ cert }); continue; }
+    let extLen; [extLen, off] = r_u16(body, off);
+    let extRaw; [extRaw, off] = r_bytes(body, off, extLen);
+    // extRaw is the list body (prefix already consumed above), so use
+    // the list parser — parse_extensions() would misread the first two
+    // bytes of the first extension as a vector length.
+    entries.push({ cert, extensions: parse_extension_list(extRaw) });
   }
-
-  return {
-    version: TLS_VERSION.TLS1_2,
-    entries: entries12
-  };
+  return tls13 ? { version: TLS_VERSION.TLS1_3, request_context, entries }
+               : { version: TLS_VERSION.TLS1_2, entries };
 }
 
 
@@ -1499,7 +1532,9 @@ function parse_certificate_verify(body) {
 
   // The signature vector ends the message; anything after it is framing junk.
   if (off !== body.length) throw parseError('trailing data after CertificateVerify signature');
-  if (slen === 0) throw parseError('empty CertificateVerify signature');
+  // An empty signature is well formed (signature<0..2^16-1>, RFC 8446
+  // §4.4.3; RFC 5246 §4.7) and does not verify: decrypt_error, from the
+  // check — not decode_error here (tlsfuzzer).
 
   return { scheme: alg, signature: sig };
 }
@@ -1548,6 +1583,8 @@ function build_new_session_ticket(p) {
 function parse_new_session_ticket(body) {
   let off = 0;
 
+  // The two u32s were read without a bounds check: a short body read as 0s.
+  if (body.length < 8) throw parseError('NewSessionTicket: truncated');
   let lifetime = (body[off]<<24 | body[off+1]<<16 | body[off+2]<<8 | body[off+3]) >>> 0; off+=4;
   let age_add  = (body[off]<<24 | body[off+1]<<16 | body[off+2]<<8 | body[off+3]) >>> 0; off+=4;
 
@@ -1567,8 +1604,10 @@ function parse_new_session_ticket(body) {
   // format; what a session then DOES with a ticket is policy and lives above.
   if (tlen === 0) throw parseError('NewSessionTicket carries an empty ticket');
 
-  let extBuf = body.subarray(off);
-  let extensions = extBuf.length ? parse_extensions(extBuf) : [];
+  // extensions<0..2^16-2> is part of the structure (RFC 8446 §4.6.1): it
+  // must be there, and it ends the message (parse_extensions refuses bytes
+  // after it). A body that stopped after the ticket passed as "no extensions".
+  let extensions = parse_extensions(body.subarray(off));
 
   return {
     ticket_lifetime: lifetime,
@@ -1757,7 +1796,10 @@ function build_hello_retry_request(params) {
   // params: { cipher_suite, selected_version, selected_group, session_id?, cookie?, other_exts? }
   let rnd = TLS13_HRR_RANDOM;
   let sid = (params && params.session_id) ? toU8(params.session_id) : new Uint8Array(0);
-  let legacy_version = TLS_VERSION.TLS1_2;
+  // The HelloRetryRequest is a ServerHello (RFC 8446 §4.1.4), with the same
+  // legacy_version: 0x0303 over TLS, {254,253} over DTLS 1.3 (RFC 9147 §5.3).
+  let legacy_version = (params && params.selected_version === DTLS_VERSION.DTLS1_3)
+    ? DTLS_VERSION.DTLS1_2 : TLS_VERSION.TLS1_2;
 
   let extList = [];
   // supported_versions (selected)
@@ -1850,31 +1892,10 @@ function parse_server_key_exchange(body) {
     return { kex: 'ECDHE', group: group, public_key: pub, sig_alg: sig_alg, signature: sig };
   }
 
-  // Basic DHE: dh_p<2>, dh_g<2>, dh_Ys<2>, then SignatureAndHashAlgorithm + signature<2>
-  let pLen;
-  [pLen, off] = r_u16(body, off);
-  let dh_p;
-  [dh_p, off] = r_bytes(body, off, pLen);
-
-  let gLen;
-  [gLen, off] = r_u16(body, off);
-  let dh_g;
-  [dh_g, off] = r_bytes(body, off, gLen);
-
-  let yLen;
-  [yLen, off] = r_u16(body, off);
-  let dh_Ys;
-  [dh_Ys, off] = r_bytes(body, off, yLen);
-
-  let sig_alg2;
-  [sig_alg2, off] = r_u16(body, off);
-
-  let s2len;
-  [s2len, off] = r_u16(body, off);
-  let sig2;
-  [sig2, off] = r_bytes(body, off, s2len);
-
-  return { kex: 'DHE', dh_p: dh_p, dh_g: dh_g, dh_Ys: dh_Ys, sig_alg: sig_alg2, signature: sig2 };
+  // Not a named curve (RFC 8422 §5.4: the only ECCurveType a TLS 1.2 ECDHE
+  // ServerKeyExchange may carry). DHE parameters were read here once — from
+  // the wrong offset — for suites this library no longer has.
+  throw parseError('ServerKeyExchange: ECCurveType ' + curve_type + ', not named_curve', TLS_ALERT.ILLEGAL_PARAMETER);
 }
 
 /* ============================== TLS 1.2 ClientKeyExchange ============================== */
@@ -1915,10 +1936,13 @@ function build_new_session_ticket_tls12(p) {
   off = w_bytes(out, off, ticket);
   return out;
 }
+// RFC 5077 §3.3: ticket_lifetime_hint, ticket<0..2^16-1>, nothing after.
 function parse_new_session_ticket_tls12(body) {
   let off=0;
+  if (body.length < 4) throw parseError('NewSessionTicket: truncated');
   let hint = (body[off]<<24 | body[off+1]<<16 | body[off+2]<<8 | body[off+3])>>>0; off+=4;
   let tlen; [tlen,off]=r_u16(body,off); let t; [t,off]=r_bytes(body,off,tlen);
+  if (off !== body.length) throw parseError('NewSessionTicket: ' + (body.length - off) + ' trailing bytes');
   return { ticket_lifetime_hint: hint, ticket: t };
 }
 
@@ -1977,11 +2001,14 @@ function build_key_update(request_update) {
 }
 
 /**
- * Parse KeyUpdate message body.
- * Returns { request_update: 0|1 }
+ * Parse KeyUpdate message body (RFC 8446 §4.6.3): one byte, 0 or 1.
+ * Returns { request_update: 0|1 }. Another length: decode_error; another
+ * value: illegal_parameter ("MUST" — it was read as 0, and a 2 passed).
  */
 function parse_key_update(body) {
-  return { request_update: body[0] || 0 };
+  if (!body || body.length !== 1) throw parseError('KeyUpdate of ' + (body ? body.length : 0) + ' bytes, not 1');
+  if (body[0] > 1) throw parseError('KeyUpdate request_update ' + body[0] + ', not 0 or 1', TLS_ALERT.ILLEGAL_PARAMETER);
+  return { request_update: body[0] };
 }
 
 
@@ -2004,15 +2031,22 @@ function build_dtls_handshake(tls_msg, msg_seq, frag_offset, frag_length) {
   if (frag_offset === undefined) frag_offset = 0;
   if (frag_length === undefined) frag_length = body.length;
 
-  let frag_body = body.subarray(frag_offset, frag_offset + frag_length);
+  return build_dtls_fragment(type, total_length, msg_seq, frag_offset, body.subarray(frag_offset, frag_offset + frag_length));
+}
 
+/**
+ * One fragment of a DTLS handshake message (RFC 6347 §4.2.2, RFC 9147
+ * §5.2): its 12-byte header — type, the whole message's length, message_seq,
+ * the fragment's offset and length — and its bytes.
+ */
+function build_dtls_fragment(type, total_length, msg_seq, frag_offset, frag_body) {
   let out = new Uint8Array(12 + frag_body.length);
   let off = 0;
   off = w_u8(out, off, type);
   off = w_u24(out, off, total_length);
   off = w_u16(out, off, msg_seq);
   off = w_u24(out, off, frag_offset);
-  off = w_u24(out, off, frag_length);
+  off = w_u24(out, off, frag_body.length);
   off = w_bytes(out, off, frag_body);
   return out;
 }
@@ -2054,23 +2088,102 @@ function build_hello_verify_request(params) {
  * Parse HelloVerifyRequest body.
  * Returns { server_version, cookie }.
  */
+// RFC 6347 §4.2.1: server_version, then cookie<0..2^8-1> — and nothing
+// after it (decode_error). Trailing bytes were ignored.
 function parse_hello_verify_request(body) {
   let off = 0;
   let server_version; [server_version, off] = r_u16(body, off);
   let cookieLen;      [cookieLen, off] = r_u8(body, off);
   let cookie = new Uint8Array(0);
   if (cookieLen > 0) { [cookie, off] = r_bytes(body, off, cookieLen); }
+  if (off !== body.length) throw parseError('HelloVerifyRequest: ' + (body.length - off) + ' trailing bytes');
   return { server_version, cookie };
 }
 
 
 /* ================================ Exports ================================= */
+
+// Warning alerts taken in a row, nothing else between: BoringSSL's limit
+// (BoGo TooManyWarningAlerts).
+const MAX_WARNING_ALERTS = 4;
+
+// The most plaintext a record carries (RFC 8446 §5.1, RFC 5246 §6.2.1):
+// 2^14 — TLS and DTLS, both directions. One constant for every layer that
+// cuts or checks records (TLSSession, TLSSocket, DTLSSession).
+const MAX_RECORD_PLAINTEXT = 16384;
+
+/**
+ * What an alert record from the peer says — one reading for TLS over TCP and
+ * DTLS, which each had their own and disagreed (an empty alert, a level that
+ * is neither, user_canceled at the fatal level). Two bytes, a level of 1 or
+ * 2 (RFC 8446 §6, RFC 5246 §7.2); an empty one is a zero-length fragment
+ * (§5.1 forbids them for alerts): unexpected_message; another length,
+ * decode_error; another level, illegal_parameter — each as
+ * { error: { alert, message } }. Otherwise { level, desc, fatal }:
+ * in TLS 1.3 every alert but close_notify and user_canceled is fatal,
+ * "regardless of the AlertLevel" (§6.2, §6); before it, the level says.
+ */
+function read_peer_alert(body, is13) {
+  if (!body || body.length === 0) return { error: { alert: TLS_ALERT.UNEXPECTED_MESSAGE, message: 'empty alert record' } };
+  if (body.length !== 2) return { error: { alert: TLS_ALERT.DECODE_ERROR, message: 'alert of ' + body.length + ' bytes, not 2' } };
+  let level = body[0], desc = body[1];
+  if (level !== TLS_ALERT_LEVEL.WARNING && level !== TLS_ALERT_LEVEL.FATAL) {
+    return { error: { alert: TLS_ALERT.ILLEGAL_PARAMETER, message: 'alert of level ' + level } };
+  }
+  let fatal = is13 ? (desc !== TLS_ALERT.CLOSE_NOTIFY && desc !== TLS_ALERT.USER_CANCELED) : level === TLS_ALERT_LEVEL.FATAL;
+  return { level: level, desc: desc, fatal: fatal };
+}
+
+// An alert's name, lowercase as the RFC writes it ('record_overflow'), or null.
+function alert_name(desc) {
+  for (const k in TLS_ALERT) if (TLS_ALERT[k] === desc) return k.toLowerCase();
+  return null;
+}
+
+/**
+ * A fatal alert of OURS, as every layer reports it — TLSSession, TLSSocket
+ * and DTLSSession alike, which gave a bare Error, one with a code, and one
+ * with neither: the message, err.alert (what we sent), err.code —
+ * ERR_SSL_<ALERT> (OpenSSL's reason codes as node:tls has them:
+ * ERR_SSL_RECORD_OVERFLOW, ERR_SSL_UNEXPECTED_MESSAGE …) unless a more
+ * precise one is given (ERR_TLS_CERT_PIN_MISMATCH). An error that already
+ * has them keeps its own.
+ */
+function local_alert_error(desc, message, code) {
+  const err = message instanceof Error ? message : new Error(message);
+  if (err.alert === undefined) err.alert = desc;
+  if (!err.code) err.code = code || ('ERR_SSL_' + (alert_name(desc) || 'alert_' + desc).toUpperCase());
+  return err;
+}
+
+/**
+ * A fatal alert the peer sent, as the error both transports report it — TLS
+ * over TCP and DTLS alike: 'peer sent fatal alert: <name> (<code>)',
+ * code ERR_TLS_ALERT_RECEIVED, err.alert the code. DTLS reported
+ * 'DTLS alert: level=2 desc=121', no code, no name.
+ */
+function peer_alert_error(desc) {
+  const err = new Error('peer sent fatal alert: ' + (alert_name(desc) || 'alert') + ' (' + desc + ')');
+  err.code = 'ERR_TLS_ALERT_RECEIVED';
+  err.alert = desc;
+  return err;
+}
+
 export {
+  build_dtls_fragment,
+  parseError,
+  local_alert_error,
+  alert_name,
+  peer_alert_error,
+  read_peer_alert,
+  MAX_WARNING_ALERTS,
+  MAX_RECORD_PLAINTEXT,
   HANDSHAKE_MESSAGE_MAX,
   TLS_VERSION,
   DTLS_VERSION,
   is_tls13_wire,
   is_tls12_wire,
+  version_name,
   TLS_CONTENT_TYPE,
   TLS_ALERT_LEVEL,
   TLS_ALERT,