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 encoded output is designed to degrade frequency analysis.

Why client-side text obfuscation?

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.

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!

Copy, capture, and create a cipher

Each Morus instance has a unique "cipher" for translating strings. Morus ciphers consist of a key (i.e., substitution-table) and index, stored in properties of the same name.

To share a cipher, simply copy these properties between instances. To clone a cipher use the cipher() method; it accepts and returns a (more) portable version of these properties. Either approach results in Morus instances that translate strings in the same manner.

Below demonstrates sharing and cloning a cipher between Morus instances, and how the encoded output is the same between all three.

var
  instA = new Morus(),
  instB = new Morus(),
  instC = new Morus();

// copy/reference the cipher properties
instB.key = instA.key;
instB.index = instA.index;

// use the cipher method
instC.cipher(instB.cipher());

// encode the string the same way using different instances
console.log(instA.encode('obfuscate me'));
console.log(instB.encode('obfuscate me'));
console.log(instC.encode('obfuscate me'));

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 an issue 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>

Note: The minified file was compressed by Closure Compiler.

Node.js

• npm install morus
• component install bemson/morus
• bower install morus

AMD

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

require.config({
  paths: {
    morus: 'my/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 for Mocha, using Chai and Sinon (via the Sinon-chai plugin).

• To review test results, visit Morus on Travis-CI.
• To run the tests in Node, run npm test.
• To run the tests in a browser, load test/index.html locally. (Unfortunately, the test will not run in IE6, 7, or 8.)

License

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

Copyright 2014, Bemi Faison