secure-ls

Secure localStorage/sessionStorage data with high level of encryption and data compression.

LIVE DEMO

Features

• Secure data with various types of encryption including AES, DES, Rabbit and RC4. (defaults to Base64 encoding).
• Compress data before storing it to localStorage to save extra bytes (defaults to true).
• Advanced API wrapper over localStorage API, providing other basic utilities.
• Save data in multiple keys inside localStorage and secure-ls will always remember it's creation.

Installation

Via NPM

npm install secure-ls

Via yarn

yarn add secure-ls

Libraries used

• Encryption / Decryption using The Cipher Algorithms

  It requires secret-key for encrypting and decrypting data securely. If custom secret-key is provided as mentioned below in APIs, then the library will pick that otherwise it will generate yet another very secure unique password key using PBKDF2, which will be further used for future API requests.

  PBKDF2 is a password-based key derivation function. In many applications of cryptography, user security is ultimately dependent on a password, and because a password usually can't be used directly as a cryptographic key, some processing is required.

  A salt provides a large set of keys for any given password, and an iteration count increases the cost of producing keys from a password, thereby also increasing the difficulty of attack.

  Eg: 55e8f5585789191d350329b9ebcf2b11 and db51d35aad96610683d5a40a70b20c39.

  For the generation of such strings, secretPhrase is being used and can be found in code easily but that won't make it unsecure, PBKDF2's layer on top of that will handle security.

• Compresion / Decompression using lz-string

Usage

• Example 1: With default settings i.e. Base64 Encoding and Data Compression

const ls = new SecureLS();

ls.set('key1', { data: 'test' }); // set key1
ls.get('key1'); // print data
// {data: 'test'}

• Example 2: With AES Encryption and Data Compression

const ls = new SecureLS({ encodingType: 'aes' });

ls.set('key1', { data: 'test' }); // set key1
ls.get('key1'); // print data
// {data: 'test'}

ls.set('key2', [1, 2, 3]); // set another key
ls.getAllKeys(); // get all keys
// ["key1", "key2"]
ls.removeAll(); // remove all keys

• Example 3: With RC4 Encryption but no Data Compression

const ls = new SecureLS({ encodingType: 'rc4', isCompression: false });

ls.set('key1', { data: 'test' }); // set key1
ls.get('key1'); // print data
// {data: 'test'}

ls.set('key2', [1, 2, 3]); // set another key
ls.getAllKeys(); // get all keys
// ["key1", "key2"]
ls.removeAll(); // remove all keys

• Example 3: With DES Encryption, no Data Compression and custom secret key

const ls = new SecureLS({ encodingType: 'des', isCompression: false, encryptionSecret: 'my-secret-key' });

ls.set('key1', { data: 'test' }); // set key1
ls.get('key1'); // print data
// {data: 'test'}

ls.set('key2', [1, 2, 3]); // set another key
ls.getAllKeys(); // get all keys
// ["key1", "key2"]
ls.removeAll(); // remove all keys

API Documentation

Create an instance / reference before using.

const ls = new SecureLS();

Contructor accepts a configurable Object with all three keys being optional.

Config Keys	default	accepts
encodingType	Base64	base64/aes/des/rabbit/rc4/''
isCompression	true	true/false
encryptionSecret	PBKDF2 value	String
encryptionNamespace	null	String
storage	localStorage	sessionStorage/localStorage or any storage object having same methods as ls/ss
metaKey	_secure__ls__metadata	String

Note: encryptionSecret will only be used for the Encryption and Decryption of data with AES, DES, RC4, RABBIT, and the library will discard it if no encoding / Base64 encoding method is choosen.

encryptionNamespace is used to make multiple instances with different encryptionSecret and/or different encryptionSecret possible.

const ls1 = new SecureLS({ encodingType: 'des', encryptionSecret: 'my-secret-key-1' });

const ls2 = new SecureLS({ encodingType: 'aes', encryptionSecret: 'my-secret-key-2' });

Examples:

• No config or empty Object i.e. Default Base64 Encoding and Data compression

const ls = new SecureLS();
// or
const ls = new SecureLS({});

• No encoding No data compression i.e. Normal way of storing data

const ls = new SecureLS({ encodingType: '', isCompression: false });

• Base64 encoding but no data compression

const ls = new SecureLS({ isCompression: false });

• AES encryption and data compression

const ls = new SecureLS({ encodingType: 'aes' });

• RC4 encryption and no data compression

const ls = new SecureLS({ encodingType: 'rc4', isCompression: false });

• RABBIT encryption, no data compression and custom encryptionSecret

const ls = new SecureLS({ encodingType: 'rc4', isCompression: false, encryptionSecret: 's3cr3tPa$$w0rd@123' });

• Any other storage apart from localStorage

  • Using sessionStorage

    const ls = new SecureLS({ encodingType: 'aes', isCompression: true, storage: sessionStorage });

  • Using any storage having same methods as localStorage/sessionStorage

    window.customSecureLsStore = {};
    const storage = {
      setItem: (key, value) => {
        window.customSecureLsStore[key] = value || '';
      },
      getItem: (key) => {
        return window.customSecureLsStore[key] || null;
      },
      removeItem: (key) => {
        delete window.customSecureLsStore[key];
      },
      clear: () => {
        window.customSecureLsStore = {};
      },
    };
    
    const ls = new SecureLS({ encodingType: 'aes', isCompression: true, storage: storage });

Methods

• set

  Saves data in specifed key in localStorage. If the key is not provided, the library will warn. Following types of JavaScript objects are supported:

  • Array
  • ArrayBuffer
  • Blob
  • Float32Array
  • Float64Array
  • Int8Array
  • Int16Array
  • Int32Array
  • Number
  • Object
  • Uint8Array
  • Uint8ClampedArray
  • Uint16Array
  • Uint32Array
  • String

  Parameter	Description
  key	key to store data in
  data	data to be stored

  ls.set('key-name', { test: 'secure-ls' });

• get

  Gets data back from specified key from the localStorage library. If the key is not provided, the library will warn.

  Parameter	Description
  key	key in which data is stored

  ls.get('key-name');

• remove

  Removes the value of a key from the localStorage. If the meta key, which stores the list of keys, is tried to be removed even if there are other keys which were created by secure-ls library, the library will warn for the action.

  Parameter	Description
  key	remove key in which data is stored

  ls.remove('key-name');

• removeAll

  Removes all the keys that were created by the secure-ls library, even the meta key.

  ls.removeAll();

• clear

  Removes all the keys ever created for that particular domain. Remember localStorage works differently for http and https protocol;

  ls.clear();

• getAllKeys

  Gets the list of keys that were created using the secure-ls library. Helpful when data needs to be retrieved for all the keys or when keys name are not known(dynamically created keys).

  getAllKeys()

  ls.getAllKeys();

Screenshot

Scripts

• npm run build - produces production version of the library under the dist folder
• npm run build-dev - produces development version of the library and runs a watcher
• npm run test - well ... it runs the tests :)

Contributing

1. Fork the repo on GitHub.
2. Clone the repo on machine.
3. Execute npm install and npm run dev.
4. Create a new branch <fix-typo> and do your work.
5. Run npm run build to build dist files and npm run test to ensure all test cases are passing.
6. Commit your changes to the branch.
7. Submit a Pull request.

Development Stack

• Webpack based src compilation & bundling and dist generation.
• ES6 as a source of writing code.
• Exports in a umd format so the library works everywhere.
• ES6 test setup with Jest
• Linting with ESLint.

Process

ES6 source files
       |
       |
    webpack
       |
       +--- babel, eslint
       |
  ready to use
     library
  in umd format

Credits

Many thanks to:

• @brix for the awesome crypto-js library for encrypting and decrypting data securely.

• @pieroxy for the lz-string js library for data compression / decompression.

Copyright and license

The MIT license (MIT)

Copyright (c) 2015-2024 Varun Malhotra

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.