quick-crypto
v1.0.0
Published
Easy way to encrypt and decrypt objects and values.
Downloads
5
Maintainers
Readme
Quick Crypto
An easy way to encrypt and decrypt objects and simple strings with TypeScript.
With this library, you can easily encrypt both complex objects and simple values.
Installation
npm install quick-crypto
Build
npm run build
Test
npm run test
Methods list:
These are the ten methods you can use from this library:
cipherObject()
decipherObject()
cipherObjects()
decipherObjects()
cipherValue()
decipherValue()
cipherValues()
decipherValues()
generateKeyAndIv()
getDefaultKeyAndIv()
Additional Notes
All cipher and decipher methods have the option to receive a custom key and iv. If they are not provided, the values will be encrypted with the default key of this library.
To generate your own key and iv, you can use the method
generateKeyAndIv()
, and if you need to know the default key and iv, you can use the methodgetDefaultKeyAndIv()
.The best approach to use this in production would be to generate custom keys and ivs with
generateKeyAndIv()
.It is possible to create your own key and iv, save them in a database, and use them to encrypt your data.
In the examples below, the encrypted values are just representative and are not the same as the real ones.
Usage
Each method will be explained below.
cipherObject
- This method is used to easily encrypt any object properties.
- You can pass an array of strings with the names of the properties of the object that you want to encrypt.
- If no key and/or iv is given, it will use the default key and/or iv.
- Below is an example of how this method works.
Signature
cipherObject<T extends Record<string, any>>(obj: T, propertiesToEncrypt?: (keyof T)[], keyCipher?: string, iv?: string): T;
Examples
Let's create an Address object to show how this method works.
import { cipherObject } from 'quick-crypto';
type Address = {
street: string,
number: number,
state: string,
city: string
};
const address: Address = {
street: 'some street',
number: 123,
state: 'NY',
city: 'New York'
};
// It will encrypt all string properties and use the default key and iv
const cryptoAddress = cipherObject<Address>(address);
console.log(cryptoAddress);
// {
// street: 'erblfebrfluierlwuhlrl738743bdwd',
// number: 123,
// state: 'jqwnkbdkwekwyeg7',
// city: 'lenkwndekuw8'
// }
// It will encrypt only the properties passed in the array in the second parameter and use the default key and iv
const cryptoAddress2 = cipherObject<Address>(address, ['street', 'city']);
console.log(cryptoAddress2);
// {
// street: 'erblfebrfluierlwuhlrl738743bdwd',
// number: 123,
// state: 'NY',
// city: 'lenkwndekuw8'
// }
Example (using custom key and iv)
import { cipherObject, generateKeyAndIv } from 'quick-crypto';
type Address = {
street: string,
number: number,
state: string,
city: string
};
const address: Address = {
street: 'some street',
number: 123,
state: 'NY',
city: 'New York'
};
// It will encrypt only the properties passed in the array in the second parameter using the generated key and iv
const { key, iv } = generateKeyAndIv();
const cryptoAddress = cipherObject<Address>(address, ['street', 'city'], key, iv);
console.log(cryptoAddress);
// {
// street: 'erblfebrfluierlwuhlrl738743bdwd',
// number: 123,
// state: 'NY',
// city: 'lenkwndekuw8'
// }
// It will encrypt all string properties using the generated key and iv
const { key: key2, iv: iv2 } = generateKeyAndIv();
const cryptoAddress2 = cipherObject<Address>(address, undefined, key2, iv2);
console.log(cryptoAddress2);
// {
// street: 'erblfebrfluierlwuhlrl738743bdwd',
// number: 123,
// state: 'dkhbcdkd',
// city: 'lenkwndekuw8'
// }
// It will encrypt all string properties using the generated key and the default iv
const { key: key3 } = generateKeyAndIv();
const cryptoAddress3 = cipherObject<Address>(address, undefined, key3);
console.log(cryptoAddress3);
// {
// street: 'erblfebrfluierlwuhlrl738743bdwd',
// number: 123,
// state: 'dkhbcdkd',
// city: 'lenkwndekuw8'
// }
decipherObject
- This method is used to decrypt an object.
- The same key and iv used to encrypt the object need to be provided.
- If the default key and/or iv were used to encrypt the object, you don't need to pass any parameters.
- Similar to the
cipherObject
method, you can pass an array of strings with the names of the object properties to be decrypted.
Signature
decipherObject<T extends Record<string, any>>(obj: T, propertiesToEncrypt?: (keyof T)[], keyCipher?: string, iv?: string): T;
Examples
To show how this method works, we will create a encrypted address object.
import { decipherObject } from 'quick-crypto';
type Address = {
street: string,
number: number,
state: string,
city: string
};
const encryptedAddress: Address = {
street: 'skjdckkdkwnjkqlklqwxwxw',
number: 123,
state: 'qlqnknslqskqnl',
city: 'endkwdxkwnjknwnjxwk'
};
// It will decrypt all string properties of the object using the default key and iv.
const decryptedAddress = decipherObject<Address>(encryptedAddress);
console.log(decryptedAddress);
// {
// street: 'some street',
// number: 123,
// state: 'NY',
// city: 'New York'
// }
// It will decrypt only the properties received in the array in the second parameter using the default key and iv.
const decryptedAddress2 = decipherObject<Address>(encryptedAddress, ['street', 'city']);
console.log(decryptedAddress2);
// {
// street: 'some street',
// number: 123,
// state: 'qlqnknslqskqnl',
// city: 'New York'
// }
Example (using custom key and iv)
import { decipherObject, generateKeyAndIv } from 'quick-crypto';
type Address = {
street: string,
number: number,
state: string,
city: string
};
const encryptedAddress: Address = {
street: 'skjdckkdkwnjkqlklqwxwxw',
number: 123,
state: 'qlqnknslqskqnl',
city: 'endkwdxkwnjknwnjxwk'
};
const { key, iv } = generateKeyAndIv();
// It will decrypt the properties using the same key and iv that were used to encrypt them.
const decryptedAddress = decipherObject<Address>(encryptedAddress, ['street', 'city'], key, iv);
console.log(decryptedAddress);
// {
// street: 'some street',
// number: 123,
// state: 'qlqnknslqskqnl',
// city: 'New York'
// }
// It will decrypt all string properties using the same key and iv that were used to encrypt them.
const decryptedAddress2 = decipherObject<Address>(encryptedAddress, undefined, key, iv);
console.log(decryptedAddress2);
// {
// street: 'some street',
// number: 123,
// state: 'NY',
// city: 'New York'
// }
Additional Notes
- To use a custom key and iv to decrypt objects, it must be the same key and iv used to encrypt the object.
- If no key and/or iv is given, the method will use the default key and iv to decrypt the object.
- Ensure that the keys and ivs used for encryption and decryption match to avoid errors.
- In the examples above, the encrypted values are just representative and are not the same as the real ones.
cipherObjects
- This method is similar to the
cipherObject
method, but it accepts an array of objects to encrypt instead of a single object. - It is used to easily encrypt any array of objects.
- You can pass an array of strings with the names of the properties you want to encrypt.
- If no key and/or IV is provided, the default key and/or IV will be used.
- It returns an array of objects of the same type as the input array.
- Below is an example demonstrating how this method works.
Signature
cipherObjects<T extends Record<string, any>>(obj: T[], propertiesToEncrypt?: (keyof T)[], keyCipher?: string, iv?: string): T[];
Examples
Let's create an Address object and an array of addresses to show how this method works:
import { cipherObjects } from 'quick-crypto';
type Address = {
street: string,
number: number,
state: string,
city: string
}
const addresses: Address[] = [
{
street: 'some street',
number: 123,
state: 'NY',
city: 'New York'
},
{
street: 'some other street',
number: 987,
state: 'CA',
city: 'San Francisco'
}
];
// Encrypts all string properties of all objects in the array using the default key and IV
const encryptedAddresses = cipherObjects<Address>(addresses);
console.log(encryptedAddresses);
// [
// {
// street: 'erblfebrfluierlwuhlrl738743bdwd',
// number: 123,
// state: 'jqwnkbdkwekwyeg7',
// city: 'lenkwndekuw8'
// },
// {
// street: 'erblfebrfluierlwuhlrl738743bdwd',
// number: 987,
// state: 'jqwnkbdkwekwyeg7',
// city: 'lenkwndekuw8'
// }
// ]
// Encrypts only the 'street' and 'city' properties of all objects in the array using the default key and IV
const encryptedAddresses2 = cipherObjects<Address>(addresses, ['street', 'city']);
console.log(encryptedAddresses2);
// [
// {
// street: 'erblfebrfluierlwuhlrl738743bdwd',
// number: 123,
// state: 'NY',
// city: 'lenkwndekuw8'
// },
// {
// street: 'erblfebrfluierlwuhlrl738743bdwd',
// number: 987,
// state: 'CA',
// city: 'lenkwndekuw8'
// }
// ]
Example (using custom key and iv)
import { cipherObjects, generateKeyAndIv } from 'quick-crypto';
type Address = {
street: string,
number: number,
state: string,
city: string
}
const addresses: Address[] = [
{
street: 'some street',
number: 123,
state: 'NY',
city: 'New York'
},
{
street: 'some other street',
number: 987,
state: 'CA',
city: 'San Francisco'
}
];
// Generate a custom key and IV
const { key, iv } = generateKeyAndIv();
// Encrypt the 'street' and 'city' properties using the custom key and IV
const encryptedAddresses = cipherObjects<Address>(addresses, ['street', 'city'], key, iv);
console.log(encryptedAddresses);
// [
// {
// street: 'erblfebrfluierlwuhlrl738743bdwd',
// number: 123,
// state: 'NY',
// city: 'lenkwndekuw8'
// },
// {
// street: 'erblfebrfluierlwuhlrl738743bdwd',
// number: 987,
// state: 'CA',
// city: 'lenkwndekuw8'
// }
// ]
// Encrypt all string properties using the custom key and IV
const encryptedAddresses2 = cipherObjects<Address>(addresses, undefined, key, iv);
console.log(encryptedAddresses2);
// [
// {
// street: 'erblfebrfluierlwuhlrl738743bdwd',
// number: 123,
// state: 'bkjsw',
// city: 'lenkwndekuw8'
// },
// {
// street: 'erblfebrfluierlwuhlrl738743bdwd',
// number: 987,
// state: 'kqjwksq',
// city: 'lenkwndekuw8'
// }
// ]
// Encrypt all string properties using the custom key and the default IV
const { key } = generateKeyAndIv();
const encryptedAddresses3 = cipherObjects<Address>(addresses, undefined, key);
console.log(encryptedAddresses3);
// [
// {
// street: 'erblfebrfluierlwuhlrl738743bdwd',
// number: 123,
// state: 'bkjsw',
// city: 'lenkwndekuw8'
// },
// {
// street: 'erblfebrfluierlwuhlrl738743bdwd',
// number: 987,
// state: 'kqjwksq',
// city: 'lenkwndekuw8'
// }
// ]
decipherObjects
- This method is similar to the
decipherObject
method, but it accepts an array of encrypted objects to decrypt instead of a single object. - It is used to easily decrypt any array of objects.
- You can pass an array of strings with the names of the properties you want to decrypt.
- If no key and/or IV is provided, the default key and/or IV will be used.
- It returns an array of objects of the same type as the input array.
- Below is an example demonstrating how this method works.
Signature
decipherObjects<T extends Record<string, any>>(obj: T[], propertiesToEncrypt?: (keyof T)[], keyCipher?: string, iv?: string): T[];
Examples
Let's create an Address object and an array of encrypted addresses to show how this method works:
import { decipherObjects } from 'quick-crypto';
type Address = {
street: string,
number: number,
state: string,
city: string
}
const encryptedAddresses: Address[] = [
{
street: 'eldnel2kwl2w2lsm22',
number: 123,
state: 'w2knsk2wjk2k',
city: 'ls2wkjnksjn2kjwnk'
},
{
street: '2kwl2wm2lwk2wl2lw',
number: 987,
state: 'kwml2mw2swkl2',
city: '2lkmw2lm2ls'
}
];
// Decrypts all string properties of all objects in the array using the default key and IV
const decryptedAddresses = decipherObjects<Address>(encryptedAddresses);
console.log(decryptedAddresses);
// [
// {
// street: 'some street',
// number: 123,
// state: 'NY',
// city: 'New York'
// },
// {
// street: 'some other street',
// number: 987,
// state: 'CA',
// city: 'San Francisco'
// }
// ]
// Decrypts only the 'street' and 'city' properties of all objects in the array using the default key and IV
const decryptedAddresses2 = decipherObjects<Address>(encryptedAddresses, ['street', 'city']);
console.log(decryptedAddresses2);
// [
// {
// street: 'some street',
// number: 123,
// state: 'w2knsk2wjk2k',
// city: 'New York'
// },
// {
// street: 'some other street',
// number: 987,
// state: 'kwml2mw2swkl2',
// city: 'San Francisco'
// }
// ]
- To use a custom key and IV to decipher objects, they must be the same key and IV used to encrypt the objects.
cipherValue, decipherValue, cipherValues, and decipherValues
- These methods are used to encrypt and decrypt strings or an array of strings.
- You can use the default key and IV, or provide a custom key and IV, similar to the other methods in this library.
Signature
cipherValue(value: string, key?: string, iv?: string): string;
decipherValue(value: string, key?: string, iv?: string): string;
cipherValues(values: string[], key?: string, iv?: string): string[];
decipherValues(values: string[], key?: string, iv?: string): string[];
Examples (Single string with default key and IV)
import { cipherValue, decipherValue } from 'quick-crypto';
const myString = 'hello';
// Encrypt the value with default key and IV
const encrypted = cipherValue(myString);
console.log(encrypted);
// jk3k3ej3bkde3
// Decrypt the value
const decrypted = decipherValue(encrypted);
console.log(decrypted);
// hello
Examples (Single string with custom key and IV)
import { cipherValue, decipherValue, generateKeyAndIv } from 'quick-crypto';
const { key, iv } = generateKeyAndIv();
const myString = 'hello';
// Encrypt the value with custom key and IV
const encrypted = cipherValue(myString, key, iv);
console.log(encrypted);
// jk3k3ej3bkde3
// Decrypt the value
const decrypted = decipherValue(encrypted, key, iv);
console.log(decrypted);
// hello
Examples (Array of strings with default key and IV)
import { cipherValues, decipherValues } from 'quick-crypto';
const myStringArray = ['hello', 'world', 'code'];
// Encrypt each value with default key and IV
const encrypted = cipherValues(myStringArray);
console.log(encrypted);
// ['ml2nkws2l', 'k2jwk2kn2', '2ljw2nkw2']
// Decrypt the values
const decrypted = decipherValues(encrypted);
console.log(decrypted);
// ['hello', 'world', 'code']
Examples (Array of strings with custom key and IV)
import { cipherValues, decipherValues, generateKeyAndIv } from 'quick-crypto';
const { key, iv } = generateKeyAndIv();
const myStringArray = ['hello', 'world', 'code'];
// Encrypt the values with custom key and IV
const encrypted = cipherValues(myStringArray, key, iv);
console.log(encrypted);
// ['ml2nkws2l', 'k2jwk2kn2', '2ljw2nkw2']
// Decrypt the values
const decrypted = decipherValues(encrypted, key, iv);
console.log(decrypted);
// ['hello', 'world', 'code']
generateKeyAndIv
- This method is used to generate a random key and IV to encrypt values.
- It returns a 32-character key and a 16-character IV.
Signature
generateKeyAndIv(): { key: string, iv: string }
Example
import { generateKeyAndIv } from 'quick-crypto';
const { key, iv } = generateKeyAndIv();
console.log(key, iv);
// 456s73667d1dadbafa935dgba3ecdfkl
// t7654wedsdr0679l
getDefaultKeyAndIv
- This method returns the default key and IV used in this library and is recommended for testing purposes.
- It returns a 32-character key and a 16-character IV.
Signature
getDefaultKeyAndIv(): { key: string, iv: string }
Example
import { getDefaultKeyAndIv } from 'quick-crypto';
const { key, iv } = getDefaultKeyAndIv();
console.log(key, iv);
// 456s73667d1dadbafa935dgba3ecdfkl
// t7654wedsdr0679l