@emqx/local-storage-encryption
Obfuscate key-value pairs in localStorage.
installation
Starting with v1.0.0
, you will need to provide your own encryption methods to use this package.
For example:
npm install crypto-js
For more details, please refer to:
npm install @emqx/local-storage-encryption
yarn
yarn add @emqx/local-storage-encryption
pnpm
pnpm add @emqx/local-storage-encryption
Motivation
This package is used to obfuscate key-value pairs in localStorage. The purpose is
to avoid directly displaying sensitive information, not real encryption. For example,
you have below key-value pairs in localStorage:
{
"username": "admin",
"password": "123456"
}
Even though the localStorage can be used carefully and correctly, the username
and password
are still exposed to the people.
This package can be used to obfuscate data like this.
How to use
Below is an example to encrypt the username and password:
import { encrypt, decrypt, encryption } from '@emqx/local-storage-encryption'
import AES from 'crypto-js/aes'
import encUtf8 from 'crypto-js/enc-utf8'
const encryptionMethods = {
encrypt: (message, key) => AES.encrypt(message, key).toString(),
decrypt: (data, key) => AES.decrypt(data, key).toString(encUtf8),
}
encryption.use = encryptionMethods
const keyToGetUserInfo = 'l4v1n'
function userInfoProvider() {
return Promise.resolve([
keyToGetUserInfo,
{ username: 'admin', password: '123456' },
])
}
encrypt({
providers: [userInfoProvider],
})
decrypt(keyToGetUserInfo).then((userInfo) => {
console.log(userInfo)
})
clear(keyToGetUserInfo)
API
storage
Although this package is used to obfuscate data in localStorage, it can also be used to obfuscate data in other backends
that implement the Storage
interface of the Web Storage API.
For example, you can use sessionStorage
instead of localStorage
:
import { storage } from '@emqx/local-storage-encryption'
storage.backend = window.sessionStorage
encryption
Before v1.0.0
, this package used crypto-js/aes
to encrypt data. But now you need to provide your own encryption methods to use this package. Below is an example:
import { encryption } from '@emqx/local-storage-encryption'
import AES from 'crypto-js/aes'
import encUtf8 from 'crypto-js/enc-utf8'
const encryptionMethods = {
encrypt: (message, key) => AES.encrypt(message, key).toString(),
decrypt: (data, key) => AES.decrypt(data, key).toString(encUtf8),
}
encryption.use = encryptionMethods
The encryption.use
receives an object with two fields: encrypt
and decrypt
.
The encrypt
function is used to encrypt the message
with the key
. The decrypt
function is used to decrypt the data
with the key
.
Both of them should return a string.
Please note that encryption.use
is only compatible with the Cipher Algorithms format. For example, crypto-js/aes
is a Cipher Algorithm, but crypto-js/md5
is not.
Assuming you want to use crypto-js/md5
as the encryption method, you need to be compatible with the API yourself.
You can refer to https://cryptojs.gitbook.io/docs/#ciphers to see how to define your encryption methods.
This change increases the flexibility of the package, facilitates its integration with existing systems and reduces the final package size.
encrypt
encrypt
is used to encrypt the data and set the encrypted data to localStorage.
It will return a Promise
that resolves to the encrypted data.
The principle it uses is to encrypt two keys first with the key
in the provider (provided key), one for the key to get the encrypted data from localStorage, and the other for the data to be encrypted.
Then it will set the encrypted keys and the encrypted value to localStorage.
Below is a table to show the relationship between the provided key, the encrypted keys, and the encrypted data in localStorage:
Key | Value |
---|
provided key | encrypted keys: [item, secretKeyToDecryptData] |
item | encrypted data |
decrypt
decrypt
helps you easily decrypt the data you encrypted before. You can also decrypt
manually if you understand the encryption principle described in #encrypt.
It will also return a Promise
that resolves to the decrypted data.
clear
clear
is used to clear the encrypted data from localStorage.
License
Under the Apache License, Version 2.0.