Merge pull request #395 from uProxy/trevj-utransformers-cleanup

remove remaining references to utransformers, shorten the interface

Author: trevj

Gruntfile.coffee

@@ -298,15 +298,7 @@ config =
     # Browserify freedom-modules in the library
     loggingProvider: Rule.browserify 'loggingprovider/freedom-module'
     echoFreedomModule: Rule.browserify 'echo/freedom-module'
-    churnPipeFreedomModule: Rule.browserify(
-        'churn-pipe/freedom-module',
-        {
-          # Emscripten, used to compile FTE and Rabbit to JS has unused
-          # require statements for `ws` and for `path` that need to be
-          # ignored.
-          ignore: ['ws', 'path']
-          browserifyOptions: { standalone: 'browserified_exports' }
-        })
+    churnPipeFreedomModule: Rule.browserify 'churn-pipe/freedom-module'
     # TODO: Make the browserified SSH stuff re-useable, e.g. freedomjs module.
     cloudInstallerFreedomModule: Rule.browserify('cloud/install/freedom-module', {
       alias : [

src/churn-pipe/churn-pipe.ts

@@ -13,6 +13,7 @@ import PassThrough = require('../transformers/passthrough');
 import promises = require('../promises/promises');
 import protean = require('../transformers/protean');
 import sequence = require('../transformers/byteSequenceShaper');
+import transformer = require('../transformers/transformer');
 
 import Socket = freedom.UdpSocket.Socket;
 
@@ -21,7 +22,7 @@ declare const freedom: freedom.FreedomInModuleEnv;
 var log :logging.Log = new logging.Log('churn-pipe');
 
 // Maps transformer names to class constructors.
-var transformers :{[name:string] : new() => Transformer} = {
+var transformers :{[name:string] : new() => transformer.Transformer} = {
   'caesar': caesar.CaesarCipher,
   'decompressionShaper': decompression.DecompressionShaper,
   'encryptionShaper': encryption.EncryptionShaper,
@@ -88,7 +89,7 @@ class Pipe {
       {};
 
   // Obfuscates and deobfuscates messages.
-  private transformer_ :Transformer;
+  private transformer_ :transformer.Transformer;
 
   // Endpoint to which incoming obfuscated messages are forwarded on each
   // interface.  The key is the interface, and the value is the port.

src/transformers/byteSequenceShaper.ts

@@ -1,8 +1,7 @@
-/// <reference path='../../../third_party/uTransformers/utransformers.d.ts' />
-
 import arraybuffers = require('../arraybuffers/arraybuffers');
 import logging = require('../logging/logging');
 import random = require('../crypto/random');
+import transformer = require('./transformer');
 
 const log :logging.Log = new logging.Log('byte sequence shaper');
 
@@ -65,7 +64,7 @@ export var sampleConfig = () : SequenceConfig => {
 }
 
 // An obfuscator that injects byte sequences.
-export class ByteSequenceShaper implements Transformer {
+export class ByteSequenceShaper implements transformer.Transformer {
   // Sequences that should be added to the outgoing packet stream.
   private addSequences_ :SequenceModel[];
 
@@ -88,12 +87,6 @@ export class ByteSequenceShaper implements Transformer {
     this.configure(JSON.stringify(sampleConfig()));
   }
 
-  // This method is required to implement the Transformer API.
-  // @param {ArrayBuffer} key Key to set, not used by this class.
-  public setKey = (key:ArrayBuffer) :void => {
-    throw new Error('setKey unimplemented');
-  }
-
   // Configure the transformer with the byte sequences to inject and the byte
   // sequences to remove.
   public configure = (json:string) :void => {
@@ -157,9 +150,6 @@ export class ByteSequenceShaper implements Transformer {
     }
   }
 
-  // No-op (we have no state or any resources to dispose).
-  public dispose = () :void => {}
-
   // Decode the byte sequences from strings in the config information
   static deserializeConfig(config :SequenceConfig)
   :[SequenceModel[], SequenceModel[]] {

src/transformers/caesar.ts

@@ -1,7 +1,6 @@
-/// <reference path='../../../third_party/uTransformers/utransformers.d.ts' />
-
 import logging = require('../logging/logging');
 import random = require('../crypto/random');
+import transformer = require('./transformer');
 
 var log :logging.Log = new logging.Log('caesar');
 
@@ -19,18 +18,14 @@ export var sampleConfig = () : Config => {
 }
 
 // Caesar cipher.
-export class CaesarCipher implements Transformer {
+export class CaesarCipher implements transformer.Transformer {
   /** Value by which bytes' values are shifted. */
   private shift_ :number;
 
   public constructor() {
     this.configure(JSON.stringify(sampleConfig()));
   }
 
-  public setKey = (key:ArrayBuffer) => {
-    throw new Error('setKey unimplemented');
-  }
-
   public configure = (json:string) : void => {
     var config = <Config>JSON.parse(json);
     if (config.key === undefined) {
@@ -52,9 +47,6 @@ export class CaesarCipher implements Transformer {
     return [buffer];
   }
 
-  // No-op (we have no state or any resources to dispose).
-  public dispose = () : void => {}
-
   /** Applies mapper to each byte of buffer. */
   private map_ = (
       buffer:ArrayBuffer,

src/transformers/decompressionShaper.ts

@@ -1,9 +1,8 @@
-/// <reference path='../../../third_party/uTransformers/utransformers.d.ts' />
-
 import arithmetic = require('./arithmetic');
 import arraybuffers = require('../arraybuffers/arraybuffers');
 import decompression = require('./decompressionShaper');
 import logging = require('../logging/logging');
+import transformer = require('./transformer');
 
 const log :logging.Log = new logging.Log('decompression shaper');
 
@@ -51,7 +50,7 @@ export function sampleConfig() :decompression.DecompressionConfig {
 //
 // The important thing to realize is that the compression algorithm is being
 // run in reverse, contrary to normal expectations.
-export class DecompressionShaper implements Transformer {
+export class DecompressionShaper implements transformer.Transformer {
   private frequencies_ :number[];
 
   private encoder_ :arithmetic.Encoder;
@@ -62,12 +61,6 @@ export class DecompressionShaper implements Transformer {
     this.configure(JSON.stringify(sampleConfig()));
   }
 
-  // This method is required to implement the Transformer API.
-  // @param {ArrayBuffer} key Key to set, not used by this class.
-  public setKey = (key :ArrayBuffer) :void => {
-    throw new Error('setKey unimplemented');
-  }
-
   // Configure using the target byte frequencies.
   public configure = (json :string) :void => {
     let config = JSON.parse(json);
@@ -125,7 +118,4 @@ export class DecompressionShaper implements Transformer {
     // Slice off the extra bytes and only return the data.
     return [encoded.slice(1, -4)];
   }
-
-  // No-op (we have no state or any resources to dispose).
-  public dispose = () :void => {}
 }

src/transformers/encryptionShaper.ts

@@ -1,9 +1,9 @@
-/// <reference path='../../../third_party/uTransformers/utransformers.d.ts' />
 /// <reference path='../../../third_party/aes-js/aes-js.d.ts' />
 
 import aes = require('aes-js');
 import arraybuffers = require('../arraybuffers/arraybuffers');
 import logging = require('../logging/logging');
+import transformer = require('./transformer');
 
 var log :logging.Log = new logging.Log('encryption shaper');
 
@@ -25,19 +25,13 @@ export var sampleConfig = () : EncryptionConfig => {
 }
 
 // A packet shaper that encrypts the packets with AES CBC.
-export class EncryptionShaper implements Transformer {
+export class EncryptionShaper implements transformer.Transformer {
   private key_ :ArrayBuffer;
 
   public constructor() {
     this.configure(JSON.stringify(sampleConfig()));
   }
 
-  // This method is required to implement the Transformer API.
-  // @param {ArrayBuffer} key Key to set, not used by this class.
-  public setKey = (key:ArrayBuffer) :void => {
-    throw new Error('setKey unimplemented');
-  }
-
   public configure = (json:string) :void => {
     var config = JSON.parse(json);
 
@@ -73,9 +67,6 @@ export class EncryptionShaper implements Transformer {
     return [this.decrypt_(iv, ciphertext)];
   }
 
-  // No-op (we have no state or any resources to dispose).
-  public dispose = () :void => {}
-
   static makeIV = () :ArrayBuffer => {
     var randomBytes = new Uint8Array(IV_SIZE);
     crypto.getRandomValues(randomBytes);

src/transformers/fragmentationShaper.ts

@@ -1,5 +1,3 @@
-/// <reference path='../../../third_party/uTransformers/utransformers.d.ts' />
-
 import arraybuffers = require('../arraybuffers/arraybuffers');
 import defragmenter = require('./defragmenter');
 import encryption = require('./encryptionShaper');
@@ -31,12 +29,6 @@ export class FragmentationShaper {
     this.configure(JSON.stringify(sampleConfig()));
   }
 
-  // This method is required to implement the Transformer API.
-  // @param {ArrayBuffer} key Key to set, not used by this class.
-  public setKey = (key :ArrayBuffer) :void => {
-    throw new Error('setKey unimplemented');
-  }
-
   // Configure with the target length.
   public configure = (json :string) :void => {
     var config = JSON.parse(json);
@@ -82,9 +74,6 @@ export class FragmentationShaper {
     }
   }
 
-  // No-op (we have no state or any resources to dispose).
-  public dispose = () :void => {}
-
   // Perform the following steps:
   // - Break buffer into one or more fragments
   // - Add fragment headers to each fragment

src/transformers/passthrough.ts

@@ -1,12 +1,10 @@
-/// <reference path='../../../third_party/uTransformers/utransformers.d.ts' />
+import transformer = require('./transformer');
 
 /** An obfuscator which does nothing. */
-class PassThrough implements Transformer {
+class PassThrough implements transformer.Transformer {
 
   public constructor() {}
 
-  public setKey = (key:ArrayBuffer) => {}
-
   public configure = (json:string) : void => {}
 
   public transform = (buffer:ArrayBuffer) : ArrayBuffer[] => {
@@ -16,8 +14,6 @@ class PassThrough implements Transformer {
   public restore = (buffer:ArrayBuffer) : ArrayBuffer[] => {
     return [buffer];
   }
-
-  public dispose = () : void => {}
 }
 
 export = PassThrough;

src/transformers/protean.ts

@@ -1,4 +1,3 @@
-/// <reference path='../../../third_party/uTransformers/utransformers.d.ts' />
 /// <reference path='../../../third_party/aes-js/aes-js.d.ts' />
 
 import arraybuffers = require('../arraybuffers/arraybuffers');
@@ -7,6 +6,7 @@ import encryption = require('./encryptionShaper');
 import fragmentation = require('./fragmentationShaper');
 import logging = require('../logging/logging');
 import sequence = require('./byteSequenceShaper');
+import transformer = require('./transformer');
 
 const log :logging.Log = new logging.Log('protean');
 
@@ -40,7 +40,7 @@ function flatMap<T,E>(input :Array<T>, mappedFunction :(element :T) => Array<E>)
 // - AES encryption
 // - decompression using arithmetic coding
 // - byte sequence injection
-export class Protean implements Transformer {
+export class Protean implements transformer.Transformer {
   // Fragmentation transformer
   private fragmenter_ :fragmentation.FragmentationShaper;
 
@@ -57,12 +57,6 @@ export class Protean implements Transformer {
     this.configure(JSON.stringify(sampleConfig()));
   }
 
-  // This method is required to implement the Transformer API.
-  // @param {ArrayBuffer} key Key to set, not used by this class.
-  public setKey = (key :ArrayBuffer) :void => {
-    throw new Error('setKey unimplemented');
-  }
-
   public configure = (json :string) :void => {
     let config = JSON.parse(json);
 
@@ -119,7 +113,4 @@ export class Protean implements Transformer {
     let defragmented = flatMap(decrypted, this.fragmenter_.restore);
     return defragmented;
   }
-
-  // No-op (we have no state or any resources to dispose).
-  public dispose = () :void => {}
 }

src/transformers/transformer.ts

@@ -0,0 +1,16 @@
+// Transforms byte arrays for purposes of network traffic obfuscation.
+export interface Transformer {
+  // Configures the transformer with an implementation-specific string.
+  // Intended to be called once, immediately after creation and before any
+  // packets are transformed or restored.
+  // TODO: remove this, configure on construction
+  configure(config: string): void;
+
+  // Returns the obfuscated form of p, as one or more (in the case of
+  // fragmentation) ArrayBuffers.
+  transform(p: ArrayBuffer): ArrayBuffer[];
+
+  // Returns a zero (if p is not the final or only fragment of a packet) or
+  // one-length list of ArrayBuffers of the original, unobfuscated form of c.
+  restore(c: ArrayBuffer): ArrayBuffer[];
+}