SimpleCrypto

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).

List of Contents

• 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

Changes Log (What's New)

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.

Getting Started

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

Installation

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 simple-crypto-js
 
# If you're using Yarn 
yarn add 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;

Documentation

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).

SimpleCrypto Class

List of SimpleCrypto constructor parameter.

List of SimpleCrypto instance's properties.

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.

Using encrypt() and decrypt()

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(_secretKey);
 
var plainText = "Hello World!";
var chiperText = 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.");

Working on Multiple Instances

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(_secretKey);
var simpleCrypto2 = new SimpleCrypto(_secretKey);
 
var plainText = "Hello World!";
// Encryption using the first instance (simpleCrypto1)
var chiperText = 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.");

Change the Secret Key

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("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.

Object Encryption

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(_secretKey);
 
var object = {
  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.

Random Key Generator

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.

Built With

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

Contribution

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

Version Management

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

Authors

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

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

License

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

Acknowledgments

• 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