lemon-tls 0.4.0 → 0.5.0

package/README.md

@@ -210,7 +210,7 @@ High-level wrapper extending `stream.Duplex`, API-compatible with Node.js [`tls.
 | `session` | `(Buffer)` | **Opaque session blob** — pass back to `connect({ session })` to resume |
 | `keyUpdate` | `(direction)` | Traffic keys refreshed: `'send'` or `'receive'` |
 | `keylog` | `(Buffer)` | SSLKEYLOGFILE-format line (for Wireshark) |
-| `clienthello` | `(raw, parsed)` | Raw ClientHello received (server, for JA3) |
+| `clienthello` | `(raw, parsed)` | ClientHello received (server side). Fires **synchronously before the ServerHello is built** — use it for JA3 fingerprinting, or to inspect the client's offered extensions (`parsed.extensions` / `getRemoteExtension`) and answer them via `set_context({ local_extensions })` (e.g. DTLS-SRTP `use_srtp`) |
 | `handshakeMessage` | `(type, raw, parsed)` | Every handshake message (debugging) |
 | `certificateRequest` | `(msg)` | Server requested a client certificate |
 | `error` | `(Error)` | TLS or transport error |
@@ -234,7 +234,7 @@ High-level wrapper extending `stream.Duplex`, API-compatible with Node.js [`tls.
 | `socket.getPeerFinished()` | Peer Finished verify_data (Buffer) |
 | `socket.getSharedSigalgs()` | Array of shared signature algorithm names (server-side) |
 | `socket.getEphemeralKeyInfo()` | `{ type: 'X25519', size: 253 }` |
-| `socket.exportKeyingMaterial(len, label, ctx)` | RFC 5705 keying material |
+| `socket.exportKeyingMaterial(len, label, ctx)` | Exported keying material — RFC 5705 on (D)TLS 1.2, RFC 8446 §7.5 on (D)TLS 1.3. Returns `null` before secrets are ready (Node throws instead). Omit `ctx` for the no-context form (≠ empty context on 1.2!) — that's what DTLS-SRTP's `'EXTRACTOR-dtls_srtp'` uses |
 | `socket.isSessionReused()` | `true` if session was resumed |
 | `socket.setMaxSendFragment(size)` | Cap outgoing record plaintext size `[512, 16384]` |
 | `socket.setServername(name)` | Set SNI (client-side, before handshake) |
@@ -262,6 +262,8 @@ High-level wrapper extending `stream.Duplex`, API-compatible with Node.js [`tls.
 | `socket.getNegotiationResult()` | `{ version, cipher, group, sni, alpn, resumed, helloRetried, ... }` |
 | `socket.rekeySend()` | Refresh outgoing encryption keys (TLS 1.3) |
 | `socket.rekeyBoth()` | Refresh keys for both directions (TLS 1.3) |
+| `socket.getRemoteExtensions()` | All extensions the peer sent in its hello: `[{ type, name, data, value }]`. On TLS 1.3 clients this is the union of ServerHello + EncryptedExtensions |
+| `socket.getRemoteExtension(type)` | One peer extension by numeric type (e.g. `14` = use_srtp, `0x39` = QUIC transport params), or `null` |
 
 ### `TLSSession`
 
@@ -269,6 +271,8 @@ The **core state machine** for a TLS connection. Performs handshake, key derivat
 
 This is the API to use for QUIC, DTLS, or any custom transport.
 
+Key methods (in addition to `set_context` / `feedDatagram`-style plumbing): `getTrafficSecrets()`, `getHandshakeSecrets()`, `exportKeyingMaterial(length, label, context?)` (RFC 5705 / RFC 8446 §7.5, version-dispatched), `getRemoteExtensions()` / `getRemoteExtension(type)` for inspecting what the peer offered, and the `'clienthello'` event — emitted **synchronously before the ServerHello is built**, so a server can read the client's offered extensions and answer them via `set_context({ local_extensions })`. `DTLSSession` and both socket classes delegate all of these.
+
 ```js
 import { TLSSession } from 'lemon-tls';
 
@@ -314,6 +318,45 @@ session.on('clienthello', (raw, parsed) => {
 });
 ```
 
+### DTLS API
+
+Everything above has a DTLS twin. Same TLS state machine underneath, same
+methods, plus datagram-specific plumbing (retransmission flights, epoch
+handling, cookie exchange):
+
+```js
+import { DTLSSession, DTLSSocket, createDTLSServer, connectDTLS } from 'lemon-tls';
+```
+
+**`DTLSSession`** — transport-less state machine (the DTLS analog of
+`TLSSession`). You move the datagrams:
+
+```js
+const dtls = new DTLSSession({
+  cert, key,
+  isServer: true,
+  minVersion: 'DTLSv1.2',      // DTLS 1.2 and 1.3 both supported
+  maxVersion: 'DTLSv1.3',
+  requestCert: true,           // mutual auth (WebRTC-style)
+  rejectUnauthorized: false,   // when doing fingerprint verification yourself
+});
+
+dtls.on('packet', (data) => udp.send(data, rport, raddr));  // outgoing datagrams
+udp.on('message', (msg) => dtls.feedDatagram(msg));         // incoming datagrams
+dtls.on('connect', () => { /* handshake done */ });
+dtls.on('data', (plaintext) => { /* decrypted app data */ });
+dtls.send(appData);
+```
+
+Delegated from the underlying `TLSSession` (identical semantics):
+`exportKeyingMaterial`, `getRemoteExtensions` / `getRemoteExtension`,
+`set_context`, `getNegotiationResult`, `getALPN`, `getPeerCertificate`,
+the `'clienthello'` event, plus `.tls` for direct access to the session.
+
+**`DTLSSocket` / `createDTLSServer` / `connectDTLS`** — UDP-transport
+wrappers over `DTLSSession`, mirroring the TCP socket layer's shape.
+The same delegated methods and events are available on the socket.
+
 ### Record Layer Module
 
 Shared encrypt/decrypt primitives for QUIC, DTLS, and custom transport consumers:
@@ -328,6 +371,62 @@ const algo = getAeadAlgo(cipherSuite);  // 'aes-128-gcm' | 'chacha20-poly1305'
 const encrypted = encryptRecord(contentType, plaintext, key, nonce, algo);
 ```
 
+
+### DTLS-SRTP (WebRTC-style key export)
+
+The full RFC 5764 flow — negotiate an SRTP profile via the `use_srtp`
+extension, then export the SRTP master keys from the handshake:
+
+```js
+import { DTLSSession } from 'lemon-tls';
+
+// Client side: offer profiles (GCM preferred, CM fallback):
+//   body = u16 list_len | u16 profiles[] | u8 mki_len(0)
+client.set_context({ local_extensions: [
+  { type: 14, data: new Uint8Array([0x00,0x04, 0x00,0x07, 0x00,0x01, 0x00]) },
+]});
+
+// Server side: pick ONE from the client's offer, before ServerHello:
+server.on('clienthello', (raw, parsed) => {
+  const offer = parsed.extensions.find(e => e.type === 14);
+  // ...parse offer.data, pick a profile `p`...
+  server.set_context({ local_extensions: [
+    { type: 14, data: new Uint8Array([0x00,0x02, p >> 8, p & 0xFF, 0x00]) },
+  ]});
+});
+
+// After 'connect' on both sides — identical on client and server:
+const km = session.exportKeyingMaterial(60, 'EXTRACTOR-dtls_srtp');
+// (60 bytes for AES_CM_128_HMAC_SHA1_80, 56 for AEAD_AES_128_GCM.
+//  Feed straight into rtp-packet's SrtpSession.fromDtlsKeyingMaterial.)
+```
+
+Works on DTLS 1.2 (answer in ServerHello) and DTLS 1.3 (answer in
+EncryptedExtensions — `getRemoteExtension` sees both transparently).
+
+### Crypto Primitives Module
+
+The key-schedule building blocks are exported for consumers that hold raw
+secrets (QUIC stacks, offline capture analysis, custom transports):
+
+```js
+import { crypto } from 'lemon-tls';
+
+crypto.hkdf_extract(hash, salt, ikm);
+crypto.hkdf_expand(hash, prk, info, len);
+crypto.hkdf_expand_label(hash, secret, label, context, len);   // TLS 1.3 form
+crypto.hmac(hash, key, data);
+crypto.tls12_prf(secret, label, seed, len, hash);              // RFC 5246 PRF
+crypto.TLS_CIPHER_SUITES;                                      // suite registry
+
+// Standalone keying-material exporters — the same primitives
+// session.exportKeyingMaterial() dispatches to. Use these directly only
+// when you hold the raw secrets yourself; live connections should call
+// the session/socket method, which picks the right one per version:
+crypto.tls12_exporter(hash, masterSecret, label, clientRandom, serverRandom, ctxOrNull, len);  // RFC 5705
+crypto.tls13_exporter(hash, exporterMasterSecret, label, ctxOrNull, len);                      // RFC 8446 §7.5
+```
+
 ## 🔧 Advanced Options (Not Available in Node.js)
 
 LemonTLS gives you control that Node.js doesn't expose - without `openssl.cnf` hacks:
@@ -444,6 +543,9 @@ For a pure-JavaScript implementation with zero native dependencies, this is with
 | ✅ | Node.js `tls` compat — **41 API methods/properties verified** |
 | ✅ | TypeScript typings bundled (`index.d.ts`) |
 | ✅ | DTLS 1.2 baseline (via `DTLSSocket` / `createDTLSServer`) |
+| ✅ | `exportKeyingMaterial` — RFC 5705 (1.2) + RFC 8446 §7.5 (1.3, proper two-stage `exporter_master_secret` derivation) |
+| ✅ | Peer-extension introspection (`getRemoteExtension(s)`) + custom `local_extensions` answered in the 1.2 ServerHello and 1.3 EncryptedExtensions |
+| ✅ | DTLS-SRTP keying flow (use_srtp negotiation + key export) verified end-to-end against rtp-packet |
 | ✅ | Zero dependencies - `node:crypto` only |
 | ✅ | **72 automated tests** (compat, resumption, data transfer) |
 | ✅ | Browser-tested (Chrome) |

package/index.js

@@ -9,6 +9,9 @@ import {
   hkdf_expand,
   hkdf_expand_label,
   hmac,
+  tls12_prf,
+  tls12_exporter,
+  tls13_exporter,
 } from './src/crypto.js';
 import * as wire from './src/wire.js';
 import * as record from './src/record.js';
@@ -43,6 +46,13 @@ var crypto = {
   hkdf_expand,
   hkdf_expand_label,
   hmac,
+  // Keying-material exporters (RFC 5705 / RFC 8446 §7.5) — standalone
+  // primitives for consumers that hold raw secrets (offline analysis,
+  // custom transports). Live sessions should prefer
+  // session.exportKeyingMaterial(), which picks the right one.
+  tls12_prf,
+  tls12_exporter,
+  tls13_exporter,
 };
 
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lemon-tls",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "TLS 1.3/1.2 implementation for Node.js - full control over cryptographic keys, record layer, and handshake. Drop-in replacement for node:tls with advanced options impossible in OpenSSL.",
   "main": "index.js",
   "type": "module",

package/src/compat.js

@@ -433,48 +433,61 @@ function toHex(buf) {
 function addCompatMethods(socket) {
   let session = socket._getTLSSession();
 
+  // Polyfill semantics: only define a method if the socket doesn't already
+  // provide it natively. TLSSocket has been growing first-class
+  // implementations (exportKeyingMaterial, getRemoteExtension(s), …) and a
+  // blind `socket.x = …` here would clobber them with a thinner shim —
+  // exactly the kind of silent duplication this layer must not create.
+  // compat.js stays what it claims to be: a gap-filler, never an override.
+  function def(name, fn) {
+    if (typeof socket[name] !== 'function') socket[name] = fn;
+  }
+
   /** Node.js compat: isSessionReused() — method form (same as isResumed getter) */
-  socket.isSessionReused = function() {
+  def('isSessionReused', function() {
     return socket.isResumed;
-  };
+  });
 
   /** Node.js compat: getFinished() */
-  socket.getFinished = function() {
+  def('getFinished', function() {
     return session.getFinished ? session.getFinished() : null;
-  };
+  });
 
   /** Node.js compat: getPeerFinished() */
-  socket.getPeerFinished = function() {
+  def('getPeerFinished', function() {
     return session.getPeerFinished ? session.getPeerFinished() : null;
-  };
+  });
 
-  /** Node.js compat: exportKeyingMaterial(length, label, context) */
-  socket.exportKeyingMaterial = function(length, label, context) {
-    return session.exportKeyingMaterial ? session.exportKeyingMaterial(length, label, context) : new Uint8Array(0);
-  };
+  /** Node.js compat: exportKeyingMaterial(length, label, context).
+   *  TLSSocket now ships this natively (RFC 5705 / RFC 8446 §7.5 via the
+   *  session) — this shim only covers older socket-likes. Same
+   *  null-until-ready convention as the native method. */
+  def('exportKeyingMaterial', function(length, label, context) {
+    return session.exportKeyingMaterial ? session.exportKeyingMaterial(length, label, context) : null;
+  });
 
   /** Node.js compat: getEphemeralKeyInfo() */
-  socket.getEphemeralKeyInfo = function() {
+  def('getEphemeralKeyInfo', function() {
     let group = session.context.selected_group;
     if (group === 0x001d) return { type: 'X25519', size: 253 };
     if (group === 0x0017) return { type: 'ECDH', name: 'prime256v1', size: 256 };
     if (group === 0x0018) return { type: 'ECDH', name: 'secp384r1', size: 384 };
     return {};
-  };
+  });
 
   /** Node.js compat: setServername(name) */
-  socket.setServername = function(name) {
+  def('setServername', function(name) {
     session.set_context({ local_sni: name });
-  };
+  });
 
   /** Node.js compat: disableRenegotiation() — no-op (renegotiation not supported) */
-  socket.disableRenegotiation = function() {};
+  def('disableRenegotiation', function() {});
 
   /** Node.js compat: address() — delegates to underlying transport */
-  socket.address = function() {
+  def('address', function() {
     try { return session.context && session.context.transport ? session.context.transport.address() : {}; }
     catch(e) { return {}; }
-  };
+  });
 }
 
 // ===================== Exports =====================

package/src/crypto.js

@@ -136,8 +136,8 @@ const TLS_CIPHER_SUITES = {
     cipher:       'CHACHA20_POLY1305',
     aead:         true,
     keylen:       32,
-    fixed_ivlen:  4,
-    record_ivlen: 8,
+    fixed_ivlen:  12,  // RFC 7905: ChaCha20 uses a full 12-byte IV, no explicit nonce
+    record_ivlen: 0,
     ivlen:        12,
     hash:         'sha256'
   },
@@ -671,6 +671,93 @@ function get_handshake_finished_with_hash(hashName, traffic_secret, transcript_h
 //  DTLS 1.3: record number encryption key (RFC 9147 §5.9)
 // ============================================================
 
+
+
+// ============================================================
+//  Keying-material exporters (RFC 5705 / RFC 8446 §7.5)
+// ============================================================
+
+/**
+ * TLS 1.3: derive the exporter_master_secret (RFC 8446 §7.1).
+ *
+ *   exporter_master_secret = Derive-Secret(Master Secret, "exp master",
+ *                                          ClientHello...server Finished)
+ *
+ * Called at the same point (and with the same transcript hash) as the
+ * application traffic secrets.
+ */
+function derive_exporter_master_secret_with_hash(hashName, master_secret, transcript_hash) {
+  let hashLen = getHashLen(hashName);
+  return hkdf_expand_label(hashName, master_secret, 'exp master', transcript_hash, hashLen);
+}
+
+/**
+ * TLS 1.3 exporter (RFC 8446 §7.5) — two-stage derivation:
+ *
+ *   TLS-Exporter(label, context_value, key_length) =
+ *     HKDF-Expand-Label(
+ *       Derive-Secret(exporter_master_secret, label, ""),
+ *       "exporter", Hash(context_value), key_length)
+ *
+ * Note the FIRST stage uses Hash("") as its context (Derive-Secret over an
+ * empty transcript), and only the SECOND stage hashes the caller's context.
+ * A single-stage HKDF-Expand-Label(secret, label, ...) is NOT conformant
+ * and will not interoperate with OpenSSL/BoringSSL exporters.
+ *
+ * @param {string}      hashName                 'sha256' | 'sha384'
+ * @param {Uint8Array}  exporter_master_secret
+ * @param {string}      label
+ * @param {Uint8Array|null} context_value        null/undefined ≡ empty (per RFC 8446)
+ * @param {number}      length
+ * @returns {Uint8Array}
+ */
+function tls13_exporter(hashName, exporter_master_secret, label, context_value, length) {
+  let hashFn  = getHashFn(hashName);
+  let hashLen = getHashLen(hashName);
+  let h_empty = hashFn(new Uint8Array(0));
+  let derived = hkdf_expand_label(hashName, exporter_master_secret, label, h_empty, hashLen);
+  let h_ctx   = hashFn(context_value || new Uint8Array(0));
+  return hkdf_expand(hashName, derived, build_hkdf_label('exporter', h_ctx, length), length);
+}
+
+/**
+ * TLS 1.2 exporter (RFC 5705).
+ *
+ *   If no context:   PRF(master_secret, label, client_random + server_random)
+ *   With context:    PRF(master_secret, label,
+ *                        client_random + server_random +
+ *                        uint16(len(context)) + context)
+ *
+ * "No context" and "empty context" produce DIFFERENT output in TLS 1.2
+ * (unlike 1.3) — pass context_value === null/undefined for the no-context
+ * form. DTLS-SRTP (RFC 5764) uses the no-context form with label
+ * 'EXTRACTOR-dtls_srtp'.
+ *
+ * The PRF hash follows the negotiated cipher suite (RFC 5246 §5 /
+ * RFC 5289): SHA-256 for *_SHA256 suites, SHA-384 for *_SHA384 suites.
+ *
+ * @param {string}      hashName        cipher suite's PRF hash
+ * @param {Uint8Array}  master_secret
+ * @param {string}      label
+ * @param {Uint8Array}  client_random   32 bytes
+ * @param {Uint8Array}  server_random   32 bytes
+ * @param {Uint8Array|null} context_value
+ * @param {number}      length
+ * @returns {Uint8Array}
+ */
+function tls12_exporter(hashName, master_secret, label, client_random, server_random, context_value, length) {
+  let seedLen = 64 + (context_value != null ? 2 + context_value.length : 0);
+  let seed = new Uint8Array(seedLen);
+  seed.set(client_random, 0);
+  seed.set(server_random, 32);
+  if (context_value != null) {
+    seed[64] = (context_value.length >>> 8) & 0xFF;
+    seed[65] =  context_value.length        & 0xFF;
+    seed.set(context_value, 66);
+  }
+  return tls12_prf(master_secret, label, seed, length, hashName);
+}
+
 function derive_sn_key(hashName, traffic_secret, cipher_suite) {
   let keylen = TLS_CIPHER_SUITES[cipher_suite].keylen;
   return hkdf_expand_label(hashName, traffic_secret, 'sn', new Uint8Array(0), keylen);
@@ -708,4 +795,7 @@ export {
   get_handshake_finished,
   get_handshake_finished_with_hash,
   derive_sn_key,
+  derive_exporter_master_secret_with_hash,
+  tls13_exporter,
+  tls12_exporter,
 };