secure-ls
Secure localStorage data with high level of encryption and data compression.
Features
- Secure data with various types of encryption including
AES,DES,RabbitandRC4. (defaults toBase64encoding). - Compress data before storing it to
localStorageto save extra bytes (defaults totrue). - Advanced API wrapper over
localStorageAPI, providing other basic utilities. - Save data in multiple keys inside
localStorageandsecure-lswill always remember it's creation.
Installation
$ npm install 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
secureunique password key using PBKDF2, which will be further used for future API requests.PBKDF2is 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:
55e8f5585789191d350329b9ebcf2b11anddb51d35aad96610683d5a40a70b20c39.For the generation of such strings,
secretPhraseis 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
defaultsettings i.e.Base64Encoding and Data Compression
> var ls = new SecureLS();
> ls.set('key1', {data: 'test'}); // set key1
> ls.get('key1'); // print data
{data: 'test'}
- Example 2: With
AESEncryption and Data Compression
> var 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
RC4Encryption but no Data Compression
> var 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
DESEncryption, no Data Compression and custom secret key
> var 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.
var 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 |
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.
var ls1 = new SecureLS({encodingType: 'des', encryptionSecret: 'my-secret-key-1'});
var ls2 = new SecureLS({encodingType: 'aes', encryptionSecret: 'my-secret-key-2'});
Examples:
- No config or empty Object i.e. Default
Base64 EncodingandData compression
var ls = new SecureLS();
// or
var ls = new SecureLS({});
- No encoding No data compression i.e.
Normalway of storing data
var ls = new SecureLS({encodingType: '', isCompression: false});
Base64encoding butnodata compression
var ls = new SecureLS({isCompression: false});
AESencryption anddata compression
var ls = new SecureLS({encodingType: 'aes'});
RC4encryption andnodata compression
var ls = new SecureLS({encodingType: 'rc4', isCompression: false});
RABBITencryption,nodata compression andcustomencryptionSecret
var ls = new SecureLS({encodingType: 'rc4', isCompression: false, encryptionSecret: 's3cr3tPa$$w0rd@123'});
Methods
-
setSaves
datain specifedkeyin 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'}) -
getGets
databack from specifiedkeyfrom 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') -
removeRemoves 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 bysecure-lslibrary, the library will warn for the action.Parameter Description key remove key in which data is stored ls.remove('key-name') -
removeAllRemoves all the keys that were created by the
secure-lslibrary, even themeta key.ls.removeAll() -
clearRemoves all the keys ever created for that particular domain. Remember localStorage works differently for
httpandhttpsprotocol;ls.clear() -
getAllKeysGets the list of keys that were created using the
secure-lslibrary. 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 thedistfoldernpm run dev- produces development version of the library and runs a watchernpm run test- well ... it runs the tests :)
Contributing
- Fork the repo on GitHub.
- Clone the repo on machine.
- Execute
npm installandnpm run dev. - Create a new branch
<fix-typo>and do your work. - Run
npm run buildto build dist files andnpm run testto ensure all test cases are passing. - Commit your changes to the branch.
- Submit a Pull request.
Development Stack
- Webpack based
srccompilation & bundling anddistgeneration. - ES6 as a source of writing code.
- Exports in a umd format so the library works everywhere.
- ES6 test setup with Mocha and Chai.
- 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.
-
@chinchang for the below open-source libraries which are used only for the Landing Page Development.
- screenlog.js - Brings console.log on the page's screen.
- superplaceholder.js - For super charging input placeholders.
Copyright and license
The MIT license (MIT)
Copyright (c) 2015-2016 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.
5 Oct 31, 2022
3 Mar 5, 2022
3.4k Dec 30, 2022
2.3k Nov 26, 2022
21.5k Jan 4, 2023
669 Nov 29, 2022
4 Jan 8, 2023
2.9k Dec 16, 2022
1.5k Dec 10, 2022
233 Dec 13, 2022
2.4k Dec 30, 2022
15 Sep 10, 2021
4 Mar 19, 2022
3 Jan 11, 2022
2 Jan 11, 2022
223 Dec 31, 2022
1.4k Dec 28, 2022
3 Jul 8, 2022
222 Dec 28, 2022