SimpleCrypto is a JavaScript library that simplify the process of encryption and decryption of JavaScript objects, as simple as just calling encrypt() and decrypt() function. This library implements brix's crypto-js library. This library is pure JavaScript library built with TypeScript targeting CommonJS ECMAScript 5 (ES5), so it is compatible with most NodeJS back-end applications or JavaScript front-end (client browser).

• SimpleCrypto
  • List of Contents
  • Changes Log (What's New)
  • Getting Started
    • Installation
  • Documentation
    • SimpleCrypto Class
    • Using encrypt() and decrypt()
    • Working on Multiple Instances
    • Change the Secret Key
    • Object Encryption
    • Random Key Generator
  • Built With
  • Contribution
  • Version Management
  • Authors
  • License
  • Acknowledgments

This fork has several changes that differ from origin. For example, creating a new instance requires an object which has several parameters (instead of just a string). This allows customization of the secret, key size, random length, algorithm, and iterations.

What's New in 2.2.0

• Fix CDN release, setting webpack output as UMD with default library name of SimpleCrypto.
• CDN now have two file you may use, the distribution file and minified distribution one.

For full changelog, please refers to CHANGELOG file.

This library is available through package manager (npm and yarn) and through jsDelivr CDN.

To get this library included on your project, first, you can use package manager like npm or yarn command to get SimpleCrypto.

# If you're using NPM
npm install --save https://github.com/ChronSyn/simple-crypto-js

# If you're using Yarn
yarn add https://github.com/ChronSyn/simple-crypto-js

Then, include SimpleCrypto your project. If you are using the new ECMAScript 6 (ECMAScript 2015) and later, you may use the new import statement:

// ES6 and later
import SimpleCrypto from "simple-crypto-js";

However, if you are using ECMAScript 5 and older, use the require statement:

// ES5 and older
var SimpleCrypto = require("simple-crypto-js").default;

SimpleCrypto has a single class with only two instance's functions and a single static function. This is by intention to keep it's simplicity. This is full documentation about the library and how to use it on your project. All examples work on both ECMAScript 6 (and later) and ECMAScript 5 (and older).

List of SimpleCrypto constructor parameter.

List of SimpleCrypto functions.

Note:

1. Function marked with static indicating a static function.
2. Function marked with deprecation indicating deprecated function that still can be used. However, it would be deprecated (and fully gone) in future version.
3. Function marked with deprecated indicating deprecated function that has been removed in this version of release.
4. The rest (not marked with anything) are normal instance's functions.

To use SimpleCrypto, first create a SimpleCrypto instance with a secret key (password). Secret key parameter MUST be defined when creating a SimpleCrypto instance.

To encrypt and decrypt data, simply use encrypt() and decrypt() function from an instance. This will use AES-CBC encryption algorithm.

// If you would like to generate a random unique key, you may use static function generateRandom() like so
// var _secretKey = SimpleCrypto.generateRandom();
// You may also set the strength of the random key, as example 256 (default is 128);
// var _secretKey = SimpleCrypto.generateRandom(256);
// Or just defined the key by yourself (key is must!)
var _secretKey = "some-unique-key";

var simpleCrypto = new SimpleCrypto({secret: _secretKey});

var plainText = "Hello World!";
var cipherText = simpleCrypto.encrypt(plainText);
console.log("Encryption process...");
console.log("Plain Text    : " + plainText);
console.log("Cipher Text   : " + cipherText);
var decipherText = simpleCrypto.decrypt(cipherText);
console.log("... and then decryption...");
console.log("Decipher Text : " + decipherText);
console.log("... done.");

You could also perform the encryption and decryption process using different SimpleCrypto instances, PROVIDED THAT the secret key ARE STAY THE SAME between the instances. For example:

var _secretKey = "some-unique-key";
var simpleCrypto1 = new SimpleCrypto({secret: _secretKey});
var simpleCrypto2 = new SimpleCrypto({secret: _secretKey});

var plainText = "Hello World!";
// Encryption using the first instance (simpleCrypto1)
var cipherText = simpleCrypto1.encrypt(plainText);
console.log("Encryption process...");
console.log("Plain Text    : " + plainText);
console.log("Cipher Text   : " + cipherText);
// Decyption using the second instance (simpleCrypto2)
var decipherText = simpleCrypto2.decrypt(cipherText);
console.log("... and then decryption...");
console.log("Decipher Text : " + decipherText);
console.log("... done.");

If you want to change the secret key of a SimpleCrypto instance, call the setSecret() function with the new secret as parameter.

var simpleCrypto = new SimpleCrypto({secret: "some-unique-key"});
simpleCrypto.setSecret("new-more-unique-key");

On version 1.1.1 and before, you may programmatically get and set the secret using it's secret property. However, since version 2.0, direct access to instance's properties are deprecated. You can't get the secret property programmatically, but still allowed to re-set the secret using the setSecret() function.

Encryption and decryption of JavaScript object literal has never been simpler than this.

To encrypt and decrypt JavaScript object literal, simply use encrypt() and decrypt() function from an instance. This will use AES-CBC encryption algorithm.

var _secretKey = SimpleCrypto.generateRandom();
var simpleCrypto = new SimpleCrypto({secret: _secretKey});

var plainObject = {
  SimpleCrypto: "is great.",
  You: "should try it!"
};
var encrypted = simpleCrypto.encrypt(plainObject);
console.log("Encryption process...");
console.log("Plain Object     : " + plainObject);
console.log("Encrypted Object : " + encrypted);
// Set the second paramter to true, then it will return object instead of string
var decrypted = simpleCrypto.decrypt(encrypted, true);
console.log("... and then decryption...");
console.log("Decrypted object : " + decrypted);
console.log("... done.");

On version 1.1.1 and before, you might have use encryptObject() and decryptObject() function. In version 2.0, this function is in deprecation and soon would be gone in future release. This is because our goal is to keep the simplicity and a single function is enough to do encryption or decryption process.

Anywhere, after importing SimpleCrypto, you may use static function generateRandom() to produce a random key based on the length of key you have provided on the parameter (default is 128).

var randomString = SimpleCrypto.generateRandom();
var randomStringCustomKey = SimpleCrypto.generateRandom(256);

Yes, and of course it is obvious, because it is a static function, you are not required to create any SimpleCrypto instances.

Written in TypeScript, built into ECMAScript 5 using the TypeScript compiler and webpack bundler.

To contribute, simply fork this project, and issue a pull request.

We use SemVer for version management. For the versions available, see the tags on this repository.

• Danang Galuh Tegar Prasetyo - Initial work - danang-id

See also the list of contributors who participated in this project.

This project is licensed under the MIT License - see the LICENSE file for details

• This library was developed to support and simplify the Secure Cookies library.
• Made available by open source and of course brix's crypto-js library