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.

Parameter	Type	Information	Default
secret	required	The secret string (key or password) that will be used to create the secret key for encryption and decryption process.	undefined

List of SimpleCrypto instance's properties.

Property	Information	Default
_secret	Contains the secret string (key or password) that will be used to create the secret key for encryption and decryption process.	undefined
_keySize	Contains a number that represent the size of the secret key.	256
_iterations	Contains a number that represent the number of iterations done to create the secret key.	100

List of SimpleCrypto functions.

Functions	Information	Parameter	Return
static generateRandom()	Generate a random string based on the key length.	length: number (optional) - The length of key used to generating random. (default: 128) expectsWordArray: boolean (optional) - If set to true, this function will return a CryptoJS.WordArray instance instead of string. (default: false)	random: string - Generated random key.
encrypt()	Encrypt data.	data: object/string/number/boolean - The data to be encrypted.	ciphered: string - Ciphered data.
decrypt()	Decrypt ciphered data.	ciphered: string - Ciphered data to be decrypted. expectsObject: boolean (optional) - If set to true, this function will return an object instead of string. Set to true if decrypted data is expected as object. (default: false) encoder: string (optional) - Encoder used transform data back to string. (default: UTF-8)	data: string/object - The decrypted data (it might be string or object, depends on expectsObject parameter).
deprecation encryptObject() use encrypt() instead	Encrypt JavaScript object literal.	object: object - The object to be enrypted.	ciphered: string - Ciphered data.
deprecation decryptObject() use decrypt() instead	Decrypt ciphered data that is expected as object and turn it back into object literal.	ciphered: string - Ciphered data to be decrypted. encoder: string (optional) - Encoder used transform data back to string. (default: UTF-8)	object: object - The decrypted object.
setSecret()	Change the secret of the instance.	secret: string - The new secret string.	void

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

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

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

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