@agentdance/node-webrtc-srtp 1.0.0

package/src/context.ts

@@ -0,0 +1,130 @@
+import { createCipheriv } from 'node:crypto';
+import {
+  ProtectionProfile,
+  SrtpKeyingMaterial,
+  SrtpContext,
+  SrtcpContext,
+} from './types.js';
+import { aes128cmKeystream } from './cipher.js';
+import { ReplayWindow } from './replay.js';
+
+// ---------------------------------------------------------------------------
+// AES-128-CM PRF  (RFC 3711 §4.3.1)
+// ---------------------------------------------------------------------------
+
+/**
+ * Derive a session key using the AES-CM key derivation function.
+ *
+ * The PRF key is the master key; the PRF input (IV) is:
+ *   PRF_input = master_salt XOR (label * 2^48) XOR (r * 2^???)
+ *
+ * For KDR=0 (the common case), r=0 and the second XOR term vanishes.
+ * The label is placed at byte offset 7 in the 14-byte salt (bit position 48).
+ *
+ * RFC 3711 §4.3.1:
+ *   x = label * 2^48  (label occupies bits 48-55 of the 112-bit salt field)
+ *
+ * @param masterKey  16-byte AES master key
+ * @param masterSalt 14-byte master salt
+ * @param label      0x00=enc, 0x01=auth, 0x02=salt
+ * @param length     Desired output length in bytes
+ * @param r          Key derivation rate index (default 0)
+ */
+export function deriveSessionKey(
+  masterKey: Buffer,
+  masterSalt: Buffer,
+  label: number,
+  length: number,
+  r: bigint = 0n,
+): Buffer {
+  if (masterSalt.length !== 14) throw new RangeError('masterSalt must be 14 bytes');
+
+  // Build the 112-bit (14-byte) x value, then zero-pad to 16 bytes (right-pad
+  // with two 0x00 bytes) to form the IV for AES-CM.
+  //
+  // x = master_salt XOR (label << 48) XOR (r << kdr_shift)
+  // For KDR = 0 the r term is zero.
+  //
+  // label << 48 places the label byte at offset 6 (0-indexed) in the 14-byte
+  // big-endian integer.
+  const x = Buffer.from(masterSalt);
+
+  // XOR in label at byte offset 7 (label is at bit position 48 of the
+  // 112-bit big-endian value, i.e. byte index 7 counting from the MSB).
+  x.writeUInt8(x.readUInt8(7) ^ (label & 0xff), 7);
+
+  // If r != 0 we XOR it into the low 8 bytes of x (bytes 6..13).
+  // KDR=0 is the common case so this branch is rarely taken.
+  if (r !== 0n) {
+    for (let i = 0; i < 8; i++) {
+      const shift = BigInt((7 - i) * 8);
+      const off = 6 + i;
+      x.writeUInt8(x.readUInt8(off) ^ Number((r >> shift) & 0xffn), off);
+    }
+  }
+
+  // Zero-pad to 16 bytes (append two 0x00 bytes) → this is the AES-CM IV
+  const iv = Buffer.alloc(16, 0);
+  x.copy(iv, 0); // x occupies bytes 0..13; bytes 14,15 remain 0
+
+  return aes128cmKeystream(masterKey, iv, length);
+}
+
+// ---------------------------------------------------------------------------
+// Tag length helpers
+// ---------------------------------------------------------------------------
+
+function authTagLength(profile: ProtectionProfile): 10 | 4 {
+  return profile === ProtectionProfile.AES_128_CM_HMAC_SHA1_32 ? 4 : 10;
+}
+
+// ---------------------------------------------------------------------------
+// Context factories
+// ---------------------------------------------------------------------------
+
+/**
+ * Derive all three SRTP session keys from the supplied master keying material
+ * and return an initialised SrtpContext.
+ */
+export function createSrtpContext(material: SrtpKeyingMaterial): SrtpContext {
+  const { masterKey, masterSalt, profile } = material;
+
+  const sessionEncKey = deriveSessionKey(masterKey, masterSalt, 0x00, 16);
+  const sessionSaltKey = deriveSessionKey(masterKey, masterSalt, 0x02, 14);
+  // Auth key is only meaningful for CM profiles; for GCM we still derive it
+  // (harmless) but it won't be used for packet authentication.
+  const sessionAuthKey = deriveSessionKey(masterKey, masterSalt, 0x01, 20);
+
+  return {
+    profile,
+    sessionEncKey,
+    sessionAuthKey,
+    sessionSaltKey,
+    index: 0n,
+    rolloverCounter: 0,
+    lastSeq: -1,
+    replayWindow: new ReplayWindow(),
+  };
+}
+
+/**
+ * Derive all three SRTCP session keys and return an initialised SrtcpContext.
+ */
+export function createSrtcpContext(material: SrtpKeyingMaterial): SrtcpContext {
+  const { masterKey, masterSalt, profile } = material;
+
+  // SRTCP uses separate labels (same label values, different contexts per
+  // spec; in practice the same KDF is used with the same master key/salt).
+  const sessionEncKey = deriveSessionKey(masterKey, masterSalt, 0x00, 16);
+  const sessionSaltKey = deriveSessionKey(masterKey, masterSalt, 0x02, 14);
+  const sessionAuthKey = deriveSessionKey(masterKey, masterSalt, 0x01, 20);
+
+  return {
+    profile,
+    sessionEncKey,
+    sessionAuthKey,
+    sessionSaltKey,
+    index: 0,
+    replayWindow: new ReplayWindow(),
+  };
+}

package/src/gcm.ts

@@ -0,0 +1,174 @@
+import { createCipheriv, createDecipheriv } from 'node:crypto';
+import { SrtpContext } from './types.js';
+
+// ---------------------------------------------------------------------------
+// AES-128-GCM  (RFC 7714)
+// ---------------------------------------------------------------------------
+
+// GCM auth tag is always 16 bytes (128-bit).
+const GCM_TAG_LENGTH = 16;
+// GCM nonce/IV is 12 bytes.
+const GCM_IV_LENGTH = 12;
+
+/**
+ * Build the 12-byte GCM IV from the 12-byte salt, SSRC, and packet index.
+ *
+ * RFC 7714 §8.1:
+ *   IV = salt XOR (SSRC placed at bytes 4..7) XOR (index placed at bytes 4..11)
+ *
+ * More precisely for SRTP (48-bit index):
+ *   - Bytes 0..3: salt[0..3] XOR 0 XOR 0   (no SSRC/index contribution)
+ *   - Bytes 4..7: salt[4..7] XOR SSRC_be32 XOR index_hi32
+ *   - Bytes 8..11: salt[8..11] XOR 0 XOR index_lo32
+ *
+ * Wait – GCM salt is typically 12 bytes, not 14.  When used inside the
+ * standard AES-CM derivation pipeline the 14-byte session salt is trimmed
+ * to 12 bytes by dropping the two trailing zero bytes (they were zero-padded
+ * anyway in the PRF output, but in practice the caller passes the full 14).
+ * We take the first 12 bytes of the supplied salt.
+ */
+function buildGcmIv(salt: Buffer, ssrc: number, index: bigint): Buffer {
+  // Use first 12 bytes; remaining 2 are the PRF zero-padding.
+  const iv = Buffer.alloc(GCM_IV_LENGTH, 0);
+  salt.copy(iv, 0, 0, GCM_IV_LENGTH);
+
+  // XOR SSRC into bytes 4..7
+  iv.writeUInt32BE(iv.readUInt32BE(4) ^ (ssrc >>> 0), 4);
+
+  // XOR 48-bit index (big-endian 6 bytes) into bytes 6..11.
+  // Store index into a temporary 8-byte buffer; bytes [2..7] hold the 48-bit value.
+  const idxBytes = Buffer.allocUnsafe(8);
+  idxBytes.writeBigUInt64BE(index & 0xffffffffffffn, 0);
+  // bytes 6..7 overlap with the SSRC field – XOR as a 16-bit word
+  iv.writeUInt16BE(iv.readUInt16BE(6) ^ idxBytes.readUInt16BE(2), 6);
+  // bytes 8..11 – XOR as a 32-bit word
+  iv.writeUInt32BE(iv.readUInt32BE(8) ^ idxBytes.readUInt32BE(4), 8);
+
+  return iv;
+}
+
+// ---------------------------------------------------------------------------
+// Parse minimal RTP header to extract SSRC and payload offset
+// ---------------------------------------------------------------------------
+
+function parseRtpHeader(packet: Buffer): { ssrc: number; headerLen: number } {
+  if (packet.length < 12) throw new RangeError('RTP packet too short');
+  const cc = packet[0]! & 0x0f;
+  const x = (packet[0]! & 0x10) !== 0;
+  let headerLen = 12 + cc * 4;
+  if (x) {
+    if (packet.length < headerLen + 4) throw new RangeError('RTP header extension truncated');
+    const extLen = packet.readUInt16BE(headerLen + 2);
+    headerLen += 4 + extLen * 4;
+  }
+  const ssrc = packet.readUInt32BE(8);
+  return { ssrc, headerLen };
+}
+
+// ---------------------------------------------------------------------------
+// GCM protect / unprotect
+// ---------------------------------------------------------------------------
+
+/**
+ * Encrypt and authenticate an SRTP packet using AES-128-GCM.
+ *
+ * Packet layout after protection:
+ *   RTP Header (AAD, unchanged) | Encrypted Payload | GCM Auth Tag (16 bytes)
+ */
+export function gcmSrtpProtect(ctx: SrtpContext, rtpPacket: Buffer): Buffer {
+  const { ssrc, headerLen } = parseRtpHeader(rtpPacket);
+  const seq = rtpPacket.readUInt16BE(2);
+
+  // Compute packet index and update context state.
+  const index = computeIndex(ctx, seq);
+
+  const iv = buildGcmIv(ctx.sessionSaltKey, ssrc, index);
+  const header = rtpPacket.subarray(0, headerLen);
+  const payload = rtpPacket.subarray(headerLen);
+
+  const cipher = createCipheriv('aes-128-gcm', ctx.sessionEncKey, iv);
+  cipher.setAAD(header);
+  const encrypted = Buffer.concat([cipher.update(payload), cipher.final()]);
+  const tag = cipher.getAuthTag();
+
+  // Update context
+  ctx.index = index;
+  ctx.rolloverCounter = Number(index >> 16n) >>> 0;
+  ctx.lastSeq = seq;
+
+  return Buffer.concat([header, encrypted, tag]);
+}
+
+/**
+ * Authenticate and decrypt a GCM-protected SRTP packet.
+ * Returns null if authentication fails or replay is detected.
+ */
+export function gcmSrtpUnprotect(ctx: SrtpContext, srtpPacket: Buffer): Buffer | null {
+  if (srtpPacket.length < 12 + GCM_TAG_LENGTH) return null;
+
+  const { ssrc, headerLen } = parseRtpHeader(srtpPacket);
+  const seq = srtpPacket.readUInt16BE(2);
+
+  const index = estimateIndex(ctx, seq);
+
+  if (!ctx.replayWindow.check(index)) return null;
+
+  const header = srtpPacket.subarray(0, headerLen);
+  const encryptedPayload = srtpPacket.subarray(headerLen, srtpPacket.length - GCM_TAG_LENGTH);
+  const tag = srtpPacket.subarray(srtpPacket.length - GCM_TAG_LENGTH);
+
+  const iv = buildGcmIv(ctx.sessionSaltKey, ssrc, index);
+
+  try {
+    const decipher = createDecipheriv('aes-128-gcm', ctx.sessionEncKey, iv);
+    decipher.setAAD(header);
+    decipher.setAuthTag(tag);
+    const decrypted = Buffer.concat([decipher.update(encryptedPayload), decipher.final()]);
+
+    ctx.replayWindow.update(index);
+    ctx.index = index;
+    ctx.rolloverCounter = Number(index >> 16n) >>> 0;
+    ctx.lastSeq = seq;
+
+    return Buffer.concat([header, decrypted]);
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Index helpers (shared logic – duplicated from protect/unprotect to keep
+// gcm.ts self-contained; in a real project you'd factor these out)
+// ---------------------------------------------------------------------------
+
+function computeIndex(ctx: SrtpContext, seq: number): bigint {
+  if (ctx.lastSeq === -1) {
+    return BigInt(ctx.rolloverCounter) << 16n | BigInt(seq);
+  }
+  const roc = BigInt(ctx.rolloverCounter);
+  const lastSeq = ctx.lastSeq;
+
+  // If seq wraps forward (65535 → 0), increment ROC
+  if (seq < lastSeq && lastSeq - seq > 0x8000) {
+    return (roc + 1n) << 16n | BigInt(seq);
+  }
+  return roc << 16n | BigInt(seq);
+}
+
+function estimateIndex(ctx: SrtpContext, seq: number): bigint {
+  if (ctx.lastSeq === -1) {
+    return BigInt(ctx.rolloverCounter) << 16n | BigInt(seq);
+  }
+  // RFC 3711 §3.3.1 index estimation
+  const v = BigInt(ctx.rolloverCounter);
+  const diff = seq - ctx.lastSeq;
+
+  if (diff > 0x8000) {
+    // seq is much less than lastSeq → different ROC (wrap back?)
+    return (v === 0n ? 0n : v - 1n) << 16n | BigInt(seq);
+  } else if (diff < -0x8000) {
+    // seq is much greater → ROC incremented
+    return (v + 1n) << 16n | BigInt(seq);
+  }
+  return v << 16n | BigInt(seq);
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+// Public API – re-export everything from the srtp package.
+
+export { ProtectionProfile } from './types.js';
+export type { SrtpKeyingMaterial, SrtpContext, SrtcpContext } from './types.js';
+
+export { createSrtpContext, createSrtcpContext, deriveSessionKey } from './context.js';
+
+export { aes128cmKeystream, computeSrtpIv, computeSrtcpIv } from './cipher.js';
+
+export { computeSrtpAuthTag, computeSrtcpAuthTag } from './auth.js';
+
+export { gcmSrtpProtect, gcmSrtpUnprotect } from './gcm.js';
+
+export { ReplayWindow } from './replay.js';
+
+export { srtpProtect, srtcpProtect } from './protect.js';
+
+export { srtpUnprotect, srtcpUnprotect } from './unprotect.js';

package/src/protect.ts

@@ -0,0 +1,160 @@
+import { SrtpContext, SrtcpContext, ProtectionProfile } from './types.js';
+import { aes128cmKeystream, computeSrtpIv, computeSrtcpIv } from './cipher.js';
+import { computeSrtpAuthTag, computeSrtcpAuthTag } from './auth.js';
+import { gcmSrtpProtect } from './gcm.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Number of authentication-tag bytes for a given profile. */
+function tagLength(profile: ProtectionProfile): 10 | 4 {
+  return profile === ProtectionProfile.AES_128_CM_HMAC_SHA1_32 ? 4 : 10;
+}
+
+/** Parse the minimum fixed RTP header fields we need. */
+function parseRtpHeader(pkt: Buffer): { seq: number; ssrc: number; headerLen: number } {
+  if (pkt.length < 12) throw new RangeError('RTP packet too short (< 12 bytes)');
+  const cc = pkt[0]! & 0x0f;
+  const x = (pkt[0]! & 0x10) !== 0;
+  let headerLen = 12 + cc * 4;
+  if (x) {
+    if (pkt.length < headerLen + 4) throw new RangeError('RTP extension header truncated');
+    const extLen = pkt.readUInt16BE(headerLen + 2);
+    headerLen += 4 + extLen * 4;
+  }
+  return {
+    seq: pkt.readUInt16BE(2),
+    ssrc: pkt.readUInt32BE(8),
+    headerLen,
+  };
+}
+
+/** Parse the minimum fixed RTCP header fields. */
+function parseRtcpHeader(pkt: Buffer): { ssrc: number } {
+  if (pkt.length < 8) throw new RangeError('RTCP packet too short (< 8 bytes)');
+  return { ssrc: pkt.readUInt32BE(4) };
+}
+
+/**
+ * Advance the packet index (and ROC) for a sender-side protect call.
+ * The index increments monotonically; ROC increments whenever the 16-bit
+ * sequence counter wraps.
+ */
+function nextSrtpIndex(ctx: SrtpContext, seq: number): bigint {
+  if (ctx.lastSeq === -1) {
+    // First packet
+    return BigInt(ctx.rolloverCounter) << 16n | BigInt(seq);
+  }
+  const roc = BigInt(ctx.rolloverCounter);
+  const lastSeq = ctx.lastSeq;
+
+  // Detect forward wrap-around (65535 → 0)
+  if (seq < lastSeq && lastSeq - seq > 0x8000) {
+    return (roc + 1n) << 16n | BigInt(seq);
+  }
+  return roc << 16n | BigInt(seq);
+}
+
+// ---------------------------------------------------------------------------
+// SRTP protect (RFC 3711 §3.1)
+// ---------------------------------------------------------------------------
+
+/**
+ * Protect (encrypt + authenticate) an RTP packet.
+ *
+ * Output layout:
+ *   RTP Header (unchanged) | Encrypted Payload | Auth Tag (10 or 4 bytes)
+ *
+ * GCM profiles are handled by delegating to `gcmSrtpProtect`.
+ */
+export function srtpProtect(ctx: SrtpContext, rtpPacket: Buffer): Buffer {
+  if (
+    ctx.profile === ProtectionProfile.AES_128_GCM ||
+    ctx.profile === ProtectionProfile.AES_256_GCM
+  ) {
+    return gcmSrtpProtect(ctx, rtpPacket);
+  }
+
+  const { seq, ssrc, headerLen } = parseRtpHeader(rtpPacket);
+  const index = nextSrtpIndex(ctx, seq);
+
+  const header = rtpPacket.subarray(0, headerLen);
+  const payload = rtpPacket.subarray(headerLen);
+
+  // 1. Encrypt the payload with AES-128-CM
+  const iv = computeSrtpIv(ctx.sessionSaltKey, ssrc, index);
+  const keystream = aes128cmKeystream(ctx.sessionEncKey, iv, payload.length);
+  const encryptedPayload = Buffer.allocUnsafe(payload.length);
+  for (let i = 0; i < payload.length; i++) {
+    encryptedPayload[i] = payload[i]! ^ keystream[i]!;
+  }
+
+  // 2. Compute HMAC-SHA1 auth tag over header || encrypted_payload || ROC
+  const roc = Number(index >> 16n) >>> 0;
+  const tag = computeSrtpAuthTag(
+    ctx.sessionAuthKey,
+    header,
+    encryptedPayload,
+    roc,
+    tagLength(ctx.profile),
+  );
+
+  // 3. Update context state
+  ctx.index = index;
+  ctx.rolloverCounter = roc;
+  ctx.lastSeq = seq;
+
+  return Buffer.concat([header, encryptedPayload, tag]);
+}
+
+// ---------------------------------------------------------------------------
+// SRTCP protect (RFC 3711 §3.4)
+// ---------------------------------------------------------------------------
+
+/**
+ * Protect (encrypt + authenticate) an RTCP packet.
+ *
+ * Output layout:
+ *   RTCP Header (8 bytes, unencrypted) |
+ *   Encrypted Remainder |
+ *   E (1 bit, always 1) | SRTCP Index (31 bits) |
+ *   Auth Tag (10 bytes)
+ */
+export function srtcpProtect(ctx: SrtcpContext, rtcpPacket: Buffer): Buffer {
+  if (rtcpPacket.length < 8) throw new RangeError('RTCP packet too short');
+
+  const { ssrc } = parseRtcpHeader(rtcpPacket);
+
+  // Increment and clamp to 31 bits
+  const index = (ctx.index + 1) & 0x7fffffff;
+  ctx.index = index;
+
+  // First 8 bytes of RTCP are left unencrypted (fixed header).
+  const header = rtcpPacket.subarray(0, 8);
+  const rest = rtcpPacket.subarray(8);
+
+  // Encrypt the rest with AES-128-CM
+  const iv = computeSrtcpIv(ctx.sessionSaltKey, ssrc, index);
+  const keystream = aes128cmKeystream(ctx.sessionEncKey, iv, rest.length);
+  const encrypted = Buffer.allocUnsafe(rest.length);
+  for (let i = 0; i < rest.length; i++) {
+    encrypted[i] = rest[i]! ^ keystream[i]!;
+  }
+
+  // Build E || SRTCP_index word (E=1 means packet is encrypted)
+  const eSrtcpIndex = 0x80000000 | (index & 0x7fffffff);
+  const indexBuf = Buffer.allocUnsafe(4);
+  indexBuf.writeUInt32BE(eSrtcpIndex >>> 0, 0);
+
+  // Auth tag covers: header || encrypted_rest || E_SRTCP_index
+  const packetForAuth = Buffer.concat([header, encrypted]);
+  const tag = computeSrtcpAuthTag(
+    ctx.sessionAuthKey,
+    packetForAuth,
+    eSrtcpIndex,
+    tagLength(ctx.profile),
+  );
+
+  return Buffer.concat([header, encrypted, indexBuf, tag]);
+}

package/src/replay.ts

@@ -0,0 +1,57 @@
+/**
+ * RFC 3711 Section 3.3.2 – Sliding window replay protection.
+ * The window tracks the highest received index and a bitmask of the
+ * WINDOW_SIZE packets below it.
+ */
+export class ReplayWindow {
+  private top: bigint = -1n;
+  private bitmask: bigint = 0n;
+  private readonly windowSize: bigint;
+
+  constructor(windowSize: bigint = 64n) {
+    this.windowSize = windowSize;
+  }
+
+  /**
+   * Returns true if the packet index is acceptable (not replayed, inside window
+   * or ahead of it).
+   */
+  check(index: bigint): boolean {
+    if (this.top === -1n) {
+      // Window not yet initialised – accept any packet.
+      return true;
+    }
+    if (index > this.top) {
+      // Ahead of the window – always accept.
+      return true;
+    }
+    const diff = this.top - index;
+    if (diff >= this.windowSize) {
+      // Too old – outside the window.
+      return false;
+    }
+    // Inside the window – accept only if not already seen.
+    const bit = 1n << diff;
+    return (this.bitmask & bit) === 0n;
+  }
+
+  /**
+   * Mark index as received and advance the window top if necessary.
+   * Must only be called after a successful auth-tag check.
+   */
+  update(index: bigint): void {
+    if (index > this.top) {
+      // Advance the window.
+      const shift = index - this.top;
+      this.bitmask = (this.bitmask << shift) | 1n;
+      this.top = index;
+    } else {
+      const diff = this.top - index;
+      const bit = 1n << diff;
+      this.bitmask |= bit;
+    }
+    // Keep bitmask bounded to windowSize bits.
+    const mask = (1n << this.windowSize) - 1n;
+    this.bitmask &= mask;
+  }
+}

package/src/types.ts

@@ -0,0 +1,55 @@
+import { ReplayWindow } from './replay.js';
+
+// ---------------------------------------------------------------------------
+// Protection profiles
+// ---------------------------------------------------------------------------
+
+export enum ProtectionProfile {
+  AES_128_CM_HMAC_SHA1_80 = 0x0001,
+  AES_128_CM_HMAC_SHA1_32 = 0x0002,
+  AES_128_GCM = 0x0007,
+  AES_256_GCM = 0x0008,
+}
+
+// ---------------------------------------------------------------------------
+// Keying material supplied by DTLS-SRTP or an external SRTP offer
+// ---------------------------------------------------------------------------
+
+export interface SrtpKeyingMaterial {
+  /** 16 bytes for AES-128 profiles; 32 bytes for AES-256 */
+  masterKey: Buffer;
+  /** 14 bytes */
+  masterSalt: Buffer;
+  profile: ProtectionProfile;
+}
+
+// ---------------------------------------------------------------------------
+// Per-stream cryptographic contexts
+// ---------------------------------------------------------------------------
+
+export interface SrtpContext {
+  profile: ProtectionProfile;
+  /** AES session encryption key */
+  sessionEncKey: Buffer;
+  /** HMAC-SHA1 authentication key – 20 bytes */
+  sessionAuthKey: Buffer;
+  /** 14-byte session salt used to compute the IV */
+  sessionSaltKey: Buffer;
+  /** Full 48-bit packet index: (ROC << 16) | SEQ */
+  index: bigint;
+  /** Roll-Over Counter */
+  rolloverCounter: number;
+  /** Last observed RTP sequence number */
+  lastSeq: number;
+  replayWindow: ReplayWindow;
+}
+
+export interface SrtcpContext {
+  profile: ProtectionProfile;
+  sessionEncKey: Buffer;
+  sessionAuthKey: Buffer;
+  sessionSaltKey: Buffer;
+  /** 31-bit SRTCP packet index (starts at 1 on first protect call) */
+  index: number;
+  replayWindow: ReplayWindow;
+}