morus

Morus

A progressive substitution cipher

by Bemi Faison

Description

Morus is a JavaScript library that uses a random substitution table (or cipher) along with a progressive index, to obfuscate text. The "progressive" part involves shifting the true substitution index by one, per character, in a string. Thus, while Morus is not encryption the output is designed to reduce any decipheral character usage patterns.

Why client-side text obfuscation?

Morus is a small effort in a larger project that necessitated secure postMessage communications. While sent messages are "private" (between the sending routine and recieving window), received messages are "public" (any one can listen in).

Generally, there is no good reason for client-side obfuscation... So for all the bad reasons, Morus was designed to be lightweight and effective.

Usage

Simply initialize a Morus instance, then encode and decode text (using the same-named methods).

var
  cipher = new Morus(),
  phrase = 'Hello world!',
  coded = cipher.encode(phrase);

console.log('original:', phrase);
// original: Hello world!

console.log('encoded:', coded, '(output will vary)');
// encoded: W1af)L@3VgaC (output will vary)

console.log('decoded:', cipher.decode(coded));
// decoded: Hello world!

Cloning the cipher and initial index

Each Morus instance has a random substitution-table and initial index, via .map and .shift properties, respectively. These properties may be (1) passed to new instances, and/or (2) copied directly, between instances. Below demonstrates both ways which ensure multiple Morus instances encode and decode text in the same manner.

var
  cipherA = new Morus(),
  // (1) pass properties to the constructor
  cipherB = new Morus(cipherA.shift, cipherA.map),
  cipherC = new Morus();

// (2) directly copy properties between instances
cipherC.map = cipherB.map;
cipherC.shift = cipherB.shift;


console.log(cipherA.encode('obfuscate me'));
console.log(cipherB.encode('obfuscate me'));
console.log(cipherC.encode('obfuscate me'));
// outputs the same (encoded) string three times

Download and Installation

Morus has no dependencies, works within modern JavaScript environments, and is available on bower, component, and npm as a CommonJS (Node) or AMD (RequireJS) module.

If Morus isn't compatible with your favorite runtime, please file a bug or pull-request (preferred).

Web Browsers

Use a <SCRIPT> tag to load the morus.min.js file in your web page. Doing so, adds Morus to the global scope.

  <script type="text/javascript" src="path/to/morus.min.js"></script>
  <script type="text/javascript">
    // ... Morus dependent code ...
  </script>

Node.js

• npm install morus if you're using npm
• component install bemson/morus if you're using component
• bower install morus if you're using Bower

AMD

Assuming you have a require.js compatible loader, configure an alias for the morus module (the alias "morus" is recommended, for consistency). The morus module exports a Morus constructor, not a module namespace.

require.config({
  paths: {
    morus: 'libs/morus'
  }
});

Then require and use the module in your application code:

require(['morus'], function (Morus) {
  // ... Morus dependent code ...
});

Testing

Morus has unit tests written with Mocha, using Chai and Sinon (via the Sinon-chai plugin).

• To browse test results, visit Morus on Travis-CI.
• To run the tests in Node, install the module or clone the git repo, then invoke npm test
• To run the tests in a browser: (1) install morus, then (2) load test/index.html locally. (Unfortunately, the tests do not run in IE6, 7, or 8.)

License

Morus is available under the terms of the MIT-License.

Copyright 2014, Bemi Faison