add an RC4-based transformer

Author: trevj

package.json

@@ -59,6 +59,7 @@
     "jasmine-core": "^2.3.4",
     "lodash": "^3.10.1",
     "request": "^2.53.0",
+    "simple-rc4": "0.0.1-b",
     "socks5-http-client": "^1.0.2",
     "ssh2": "0.5.0",
     "tslint": "^3.3.0",

src/churn-pipe/churn-pipe.ts

@@ -12,6 +12,7 @@ import net = require('../net/net.types');
 import PassThrough = require('../transformers/passthrough');
 import promises = require('../promises/promises');
 import protean = require('../transformers/protean');
+import rc4 = require('../transformers/rc4');
 import sequence = require('../transformers/byteSequenceShaper');
 import transformer = require('../transformers/transformer');
 
@@ -29,6 +30,7 @@ var transformers :{[name:string] : new() => transformer.Transformer} = {
   'fragmentationShaper': fragmentation.FragmentationShaper,
   'none': PassThrough,
   'protean': protean.Protean,
+  'rc4': rc4.Rc4Transformer,
   'sequenceShaper': sequence.ByteSequenceShaper
 };
 

src/transformers/rc4.spec.ts

@@ -0,0 +1,25 @@
+/// <reference path='../../../third_party/typings/browser.d.ts' />
+
+import freedomMocker = require('../freedom/mocks/mock-freedom-in-module-env');
+declare let freedom: freedom.FreedomInModuleEnv;
+freedom = freedomMocker.makeMockFreedomInModuleEnv();
+
+import arraybuffers = require('../arraybuffers/arraybuffers');
+import rc4 = require('./rc4');
+
+describe('rc4 transformer', function() {
+  let transformer: rc4.Rc4Transformer;
+
+  beforeEach(function() {
+    transformer = new rc4.Rc4Transformer();
+  });
+
+  it('simple transform/restore', function() {
+    const p = new Uint8Array([0, 1, 2]);
+
+    const transformedFragments = transformer.transform(p);
+    const result = transformer.restore(transformedFragments[0])[0];
+
+    expect(arraybuffers.byteEquality(p, result)).toBeTruthy();
+  });
+});

src/transformers/rc4.ts

@@ -0,0 +1,101 @@
+/// <reference path='../../../third_party/sha1/sha1.d.ts' />
+/// <reference path='../../../third_party/simple-rc4/simple-rc4.d.ts' />
+/// <reference path='../../../third_party/typings/browser.d.ts' />
+
+import logging = require('../logging/logging');
+import rc4 = require('simple-rc4');
+import sha1 = require('crypto/sha1');
+import transformer = require('./transformer');
+
+const log = new logging.Log('rc4 transformer');
+
+// Accepted in serialised form by configure().
+export interface Config {
+  key: string
+}
+
+const KEY_LENGTH_BYTES = 16;
+const R_LENGTH_BYTES = 8;
+const TRUNCATED_IV_LENGTH_BYTES = 8;
+
+// Creates a sample (non-random) config, suitable for testing.
+export function sampleConfig(): Config {
+  return {
+    key: new Buffer(KEY_LENGTH_BYTES).fill(0).toString('hex')
+  };
+}
+
+// Fast, uniformly random transformer with minimal length expansion, via RC4.
+// From a proposal by kpdyer.
+//
+// Terminology:
+//  - K: 128-bit session key, negotiated through the signalling channel
+//  - RANDOM(N): a cryptographically secure N-byte string
+//  - X[n,...,m]: the (m - n + 1) bytes starting at byte-index n of X
+//  - |X|: length, in bytes, of X
+//
+// Pseudo-code:
+//   def Encrypt(K, P):
+//     R = RANDOM(8)
+//     IV = SHA1(K || R)
+//     RET R || RC4(IV[0,...,7], P)
+//
+//   def Decrypt(K1, C):
+//     R = C[0,...,7]
+//     IV = SHA1(K1 || R)
+//     RET RC4(IV[0,...,7], C[8,...,|C | -1])
+export class Rc4Transformer implements transformer.Transformer {
+  private key_: Buffer;
+
+  public constructor() {
+    this.configure(JSON.stringify(sampleConfig()));
+  }
+
+  public configure = (json: string): void => {
+    try {
+      const config = <Config>JSON.parse(json);
+      if (config.key === undefined) {
+        throw new Error("must set key parameter");
+      }
+      const key = new Buffer(config.key, 'hex');
+      if (key.byteLength !== KEY_LENGTH_BYTES) {
+        throw new Error('keys must be ' + KEY_LENGTH_BYTES + ' bytes in length');
+      }
+      this.key_ = key;
+    } catch (e) {
+      throw new Error('could not parse config: ' + e.message);
+    }
+  }
+
+  // Applies RC4(IV[0,...,7] to bytes, as described in the pseudocode above.
+  private update_ = (r: Buffer, bytes:Buffer): void => {
+    // TODO: use the crypto module and avoid string conversion
+    const iv = sha1.str_sha1(Buffer.concat([this.key_, r]).toString('binary'));
+    const truncatedIv = new Buffer(iv, 'binary').slice(0, TRUNCATED_IV_LENGTH_BYTES);
+    new rc4(truncatedIv).update(bytes);
+  }
+
+  public transform = (ab: ArrayBuffer): ArrayBuffer[] => {
+    const p = new Buffer(ab);
+
+    const r = new Buffer(R_LENGTH_BYTES);
+    crypto.getRandomValues(r);
+
+    this.update_(r, p);
+
+    return [Buffer.concat([r, p]).buffer];
+  }
+
+  public restore = (ab: ArrayBuffer): ArrayBuffer[] => {
+    const c = new Buffer(ab);
+
+    const r = c.slice(0, R_LENGTH_BYTES);
+    const tail = c.slice(R_LENGTH_BYTES);
+    this.update_(r, tail);
+
+    // Because tail is constructed via Buffer#slice, its buffer field
+    // still references ab, which still includes r.
+    const slicedResult = tail.buffer.slice(8);
+    return [slicedResult];
+  }
+}

third_party/simple-rc4/simple-rc4.d.ts

@@ -0,0 +1,13 @@
+// TypeScript typings for:
+//   https://www.npmjs.com/package/simple-rc4
+
+declare module 'simple-rc4' {
+  class RC4 {
+    constructor(key:Buffer);
+
+    // Returns the supplied Buffer, encoded.
+    update(msg: Buffer): Buffer;
+  }
+
+  export = RC4;
+}