lemon-tls 0.2.1 → 0.3.0

package/src/session/message.js

@@ -68,6 +68,15 @@ function normalize_hello(hello) {
         out.heartbeat = value;
       } else if (name === 'USE_SRTP') {
         out.use_srtp = value;
+      } else if (name === 'SESSION_TICKET') {
+        // RFC 5077: opaque ticket bytes (TLS 1.2)
+        // Empty in ClientHello = client supports tickets / non-empty = resume using this ticket
+        // Empty in ServerHello = server will send NewSessionTicket
+        out.session_ticket = value;
+        out.session_ticket_supported = true;
+      } else if (name === 'EXTENDED_MASTER_SECRET') {
+        // RFC 7627: presence signals EMS support
+        out.extended_master_secret = true;
       } else {
         if (!('unknown' in out)) out.unknown = [];
         out.unknown.push(e);
@@ -97,10 +106,12 @@ function build_tls_message(params) {
 
   if (params.type == 'server_hello') {
     type = wire.TLS_MESSAGE_TYPE.SERVER_HELLO;
-    body = wire.build_hello('server', params);
+    params.kind = 'server';
+    body = wire.build_hello(params);
   } else if (params.type == 'client_hello') {
     type = wire.TLS_MESSAGE_TYPE.CLIENT_HELLO;
-    body = wire.build_hello('client', params);
+    params.kind = 'client';
+    body = wire.build_hello(params);
   } else if (params.type == 'server_key_exchange') {
     type = wire.TLS_MESSAGE_TYPE.SERVER_KEY_EXCHANGE;
     body = wire.build_server_key_exchange_ecdhe(params);
@@ -131,6 +142,12 @@ function build_tls_message(params) {
   } else if (params.type == 'hello_retry_request') {
     type = wire.TLS_MESSAGE_TYPE.SERVER_HELLO; // HRR uses ServerHello type with magic random
     body = wire.build_hello_retry_request(params);
+  } else if (params.type == 'new_session_ticket_tls12') {
+    type = wire.TLS_MESSAGE_TYPE.NEW_SESSION_TICKET;
+    body = wire.build_new_session_ticket_tls12(params);
+  } else if (params.type == 'new_session_ticket') {
+    type = wire.TLS_MESSAGE_TYPE.NEW_SESSION_TICKET;
+    body = wire.build_new_session_ticket(params);
   }
 
   return wire.build_message(type, body);
@@ -139,13 +156,17 @@ function build_tls_message(params) {
 
 /**
  * Parse a raw TLS handshake message into a typed object.
+ * @param {Uint8Array} data            — handshake message bytes
+ * @param {number}     [negotiatedVersion] — optional; 0x0303 for TLS 1.2, 0x0304 for TLS 1.3.
+ *                                           Needed to disambiguate NewSessionTicket wire format.
  */
-function parse_tls_message(data) {
+function parse_tls_message(data, negotiatedVersion) {
   let out = {};
   let message = wire.parse_message(data);
 
   if (message.type == wire.TLS_MESSAGE_TYPE.CLIENT_HELLO || message.type == wire.TLS_MESSAGE_TYPE.SERVER_HELLO) {
-    let hello = wire.parse_hello(message.type, message.body);
+    let kind = (message.type == wire.TLS_MESSAGE_TYPE.CLIENT_HELLO) ? 'client' : 'server';
+    let hello = wire.parse_hello({ kind: kind, body: message.body });
     out = normalize_hello(hello);
 
   } else if (message.type == wire.TLS_MESSAGE_TYPE.SERVER_KEY_EXCHANGE) {
@@ -180,7 +201,14 @@ function parse_tls_message(data) {
     out.body = message.body;
 
   } else if (message.type == wire.TLS_MESSAGE_TYPE.NEW_SESSION_TICKET) {
-    out = wire.parse_new_session_ticket(message.body);
+    // TLS 1.2 and 1.3 have different wire formats for this message.
+    // TLS 1.3: ticket_lifetime | ticket_age_add | ticket_nonce | ticket | extensions
+    // TLS 1.2: ticket_lifetime_hint | ticket                     (RFC 5077)
+    if (negotiatedVersion === 0x0303) {
+      out = wire.parse_new_session_ticket_tls12(message.body);
+    } else {
+      out = wire.parse_new_session_ticket(message.body);
+    }
     out.type = 'new_session_ticket';
 
   } else if (message.type == wire.TLS_MESSAGE_TYPE.KEY_UPDATE) {

package/src/session/ticket.js

@@ -0,0 +1,185 @@
+/**
+ * Session ticket / session blob encoding & decoding.
+ *
+ * Two distinct blob types:
+ *
+ * 1. SERVER blob (encrypted) — issued by server to client (TLS 1.3 NewSessionTicket,
+ *    TLS 1.2 NewSessionTicket), or to user's store (TLS 1.2 Session IDs via 'newSession' event).
+ *    Client/store returns it back; server decrypts with its ticketKeys.
+ *
+ *    Format: key_name(16) | IV(12) | Ciphertext(AES-256-GCM) | Tag(16)
+ *    ticketKeys layout: [0:16]=key_name, [16:48]=AES-256-GCM key
+ *
+ * 2. CLIENT blob (plaintext) — returned by TLSSocket to the user via 'session' event;
+ *    user passes it back in tls.connect({ session }). JSON-encoded, not encrypted —
+ *    user is responsible for secure storage (same convention as Node.js).
+ */
+
+import * as crypto from 'node:crypto';
+import { uint8Equal } from '../utils.js';
+
+/* =========================================================================
+ *                      SERVER-SIDE ENCRYPTED BLOB
+ * ========================================================================= */
+
+const KEY_NAME_LEN = 16;
+const IV_LEN       = 12;
+const TAG_LEN      = 16;
+
+/**
+ * Split ticketKeys (48 bytes) into key_name (16) + aes key (32).
+ * Throws if ticketKeys is malformed.
+ */
+function split_ticket_keys(ticketKeys) {
+    if (!ticketKeys) throw new Error('ticketKeys is required');
+    let buf = Buffer.isBuffer(ticketKeys) ? ticketKeys : Buffer.from(ticketKeys);
+    if (buf.length !== 48) throw new Error('ticketKeys must be exactly 48 bytes');
+    return {
+        key_name: buf.slice(0, 16),
+        aes_key:  buf.slice(16, 48),
+    };
+}
+
+/**
+ * Encrypt a server-side session state into an opaque blob.
+ *
+ * @param {Object} state       — session state (version, cipher, master_secret, ...)
+ * @param {Buffer} ticketKeys  — 48 bytes (key_name + aes_key)
+ * @returns {Uint8Array}       — key_name(16) | IV(12) | CT | Tag(16)
+ */
+function encrypt_session_blob(state, ticketKeys) {
+    let { key_name, aes_key } = split_ticket_keys(ticketKeys);
+
+    // Serialize state → JSON with Uint8Array fields base64-encoded
+    let serialized = Buffer.from(JSON.stringify(serialize_state(state)));
+
+    let iv = crypto.randomBytes(IV_LEN);
+    let cipher = crypto.createCipheriv('aes-256-gcm', aes_key, iv);
+    let ct = cipher.update(serialized);
+    cipher.final();
+    let tag = cipher.getAuthTag();
+
+    let out = Buffer.concat([key_name, iv, ct, tag]);
+    return new Uint8Array(out);
+}
+
+/**
+ * Decrypt a server-side session blob.
+ *
+ * @param {Uint8Array} blob        — encrypted blob
+ * @param {Buffer}     ticketKeys  — 48 bytes. Must match the key_name embedded in blob.
+ * @returns {Object|null}          — state, or null if decryption failed (wrong key_name, tampered data, etc).
+ */
+function decrypt_session_blob(blob, ticketKeys) {
+    try {
+        if (!blob || blob.length < KEY_NAME_LEN + IV_LEN + TAG_LEN) return null;
+        let buf = Buffer.isBuffer(blob) ? blob : Buffer.from(blob);
+
+        let blob_key_name = buf.slice(0, KEY_NAME_LEN);
+        let iv            = buf.slice(KEY_NAME_LEN, KEY_NAME_LEN + IV_LEN);
+        let tag           = buf.slice(buf.length - TAG_LEN);
+        let ct            = buf.slice(KEY_NAME_LEN + IV_LEN, buf.length - TAG_LEN);
+
+        let { key_name, aes_key } = split_ticket_keys(ticketKeys);
+
+        // Verify key_name matches (allows rotation — caller may try multiple keys)
+        if (!uint8Equal(blob_key_name, key_name)) return null;
+
+        let decipher = crypto.createDecipheriv('aes-256-gcm', aes_key, iv);
+        decipher.setAuthTag(tag);
+        let pt = decipher.update(ct);
+        decipher.final(); // throws on tag mismatch
+
+        let state = deserialize_state(JSON.parse(pt.toString('utf8')));
+        return state;
+    } catch (e) {
+        return null;
+    }
+}
+
+/* =========================================================================
+ *                      CLIENT-SIDE PLAINTEXT BLOB
+ * ========================================================================= */
+
+/**
+ * Encode a client-side session blob. JSON-serialized, NOT encrypted.
+ * User is responsible for secure storage (this contains the master_secret).
+ *
+ * @param {Object} state
+ * @returns {Uint8Array} — utf-8 encoded JSON
+ */
+function encode_client_session(state) {
+    let serialized = JSON.stringify(serialize_state(state));
+    return new Uint8Array(Buffer.from(serialized, 'utf8'));
+}
+
+/**
+ * Decode a client-side session blob.
+ *
+ * @param {Uint8Array|Buffer} blob
+ * @returns {Object|null}
+ */
+function decode_client_session(blob) {
+    try {
+        if (!blob || blob.length === 0) return null;
+        let buf = Buffer.isBuffer(blob) ? blob : Buffer.from(blob);
+        return deserialize_state(JSON.parse(buf.toString('utf8')));
+    } catch (e) {
+        return null;
+    }
+}
+
+/* =========================================================================
+ *                      SERIALIZATION HELPERS
+ * ========================================================================= */
+
+/**
+ * Convert state object to JSON-safe form.
+ * Uint8Array/Buffer fields → { $b: base64 }
+ */
+function serialize_state(state) {
+    let out = {};
+    for (let k in state) {
+        let v = state[k];
+        if (v == null) {
+            out[k] = null;
+        } else if (v instanceof Uint8Array || Buffer.isBuffer(v)) {
+            out[k] = { $b: Buffer.from(v).toString('base64') };
+        } else if (typeof v === 'object' && !Array.isArray(v)) {
+            out[k] = serialize_state(v);
+        } else {
+            out[k] = v;
+        }
+    }
+    return out;
+}
+
+/**
+ * Convert JSON-decoded form back to state object.
+ * { $b: base64 } → Uint8Array
+ */
+function deserialize_state(obj) {
+    if (obj == null) return null;
+    let out = {};
+    for (let k in obj) {
+        let v = obj[k];
+        if (v == null) {
+            out[k] = null;
+        } else if (typeof v === 'object' && typeof v.$b === 'string' && Object.keys(v).length === 1) {
+            out[k] = new Uint8Array(Buffer.from(v.$b, 'base64'));
+        } else if (typeof v === 'object' && !Array.isArray(v)) {
+            out[k] = deserialize_state(v);
+        } else {
+            out[k] = v;
+        }
+    }
+    return out;
+}
+
+export {
+    encrypt_session_blob,
+    decrypt_session_blob,
+    encode_client_session,
+    decode_client_session,
+    split_ticket_keys,
+};