symmetric-cipher.js
This is a lightweight library meant for symmetric encryption and decryption of strings. It is written for express-js to add support for encrypted cookies, but will also work with Node.js.
This library currently only allows users to use 'AES-256-CBC' symmetric algorithm. On encryption, a random IV is computed and prepended to the ciphertext with :
as the separator. This library uses the in-built Node.js crypto
library under the hood.
256-bit (32-byte) keys are required for encryption or decryption. To avoid imposing strict requirements, this library automatically generates a sha256 hash of the key if it is not the required length. However, it is not recommended to use short keys like 'super secret key', though they will still work.
See the Security section for tips on generating keys.
Installation
NPM
npm install symmetric-cipher.js
Yarn
yarn add symmetric-cipher.js
Compatibility
This library is a commonJS library compatible with Node >= 0.10
Usage
var cipher = require('symmetric-cipher.js');
// Encrypt
cipher.encrypt('my value', 'super secret key');
// rSgTZLgXrFlpAOQkUuTgmQ==:wb/6vFECOGRCSA3DSVLpjw==
// Decrypt
cipher.decrypt('rSgTZLgXrFlpAOQkUuTgmQ==:wb/6vFECOGRCSA3DSVLpjw==', 'super secret key');
// my value
ES Modules
import cipher from 'symmetric-cipher.js';
// Encrypt
cipher.encrypt('my value', 'super secret key');
// rSgTZLgXrFlpAOQkUuTgmQ==:wb/6vFECOGRCSA3DSVLpjw==
// Decrypt
cipher.decrypt('rSgTZLgXrFlpAOQkUuTgmQ==:wb/6vFECOGRCSA3DSVLpjw==', 'super secret key');
// my value
Named imports may also work for Node >= 14.13.0.
Security
The key used for encryption and decryption should be a long, random string. The longer the key, the more secure the encryption. A 32-byte (256-bit) key in this case is sufficient. The key should be stored securely.
Generating a base64 key (Recommended)
node
crypto.randomBytes(32).toString('base64')
Example: ktFZQO5JDd4wjwPB2U6bawZKUTGbgOfw6up0wFtjsVk=
Generating a hex key
node
crypto.randomBytes(32).toString('hex')
Example: 37f3ce113b34e789ae76ee238c8aa349a6b163e81c283144bffb9c17328360d1
NOTE: For keys generated by the above commands, don't forget to specify the encoding. See the Examples section below.
Store the key securely. For Node.js, you can store it in a .env
file and use dotenv library to load it into your application. Don't store your key in version control. Add .env
to .gitignore
.
API
decodeKey(key, keyEncoding)
This is a helper function that converts a key to a Buffer object (binary). It leaves Buffer objects intact. It is used internally by the encrypt and decrypt functions.
-
key
: (string | Buffer) The secret used for encryption or decryption. If it is a string, it is converted from the specified encoding to binary. -
keyEncoding
(string) The encoding of the key. Default isutf8
. Others includebase64
,hex
,ascii
. For full details see crypto's BufferEncoding.
encrypt(plainText, key, keyEncoding)
-
plaintext
(string) The string to encrypt -
key
: (string | Buffer) The secret used for encryption or decryption. If it is a string, it is converted from the specified encoding to binary. -
keyEncoding
(string) The encoding of the key. Default isutf8
. Others includebase64
,hex
,ascii
. For full details see crypto's BufferEncoding.
Output is in the format {24-character-iv}:{ciphertext} in base64 encoding.
decrypt(cipherText, key, keyEncoding)
Expected input is in the format {24-character-iv}:{ciphertext} in base64 encoding.
-
cipherText
(string) The cipher to decrypt -
key
: (string | Buffer) The secret used for encryption or decryption. If it is a string, it is converted from the specified encoding to binary. -
keyEncoding
(string) The encoding of the key. Default is 'utf8'. Others include 'base64', 'hex', 'ascii'. For full details see crypto's BufferEncoding.
Output is the original plaintext.
Examples
Base64 key (Recommended)
var cipher = require('symmetric-cipher.js');
cipher.encrypt('my value', 'P6wVBCUaAnRlmBNG+1sNV9OY5N9KAyU6TH0ZJuQOmQc=', 'base64')
cipher.decrypt('y3axcNW9eA6ggJNYWotsUQ==:k+YSdJ1MBZct/0bOtQ/zvA==', 'P6wVBCUaAnRlmBNG+1sNV9OY5N9KAyU6TH0ZJuQOmQc=', 'base64')
Key as Buffer object (binary)
var cipher = require('symmetric-cipher.js');
var key = cipher.decodeKey('P6wVBCUaAnRlmBNG+1sNV9OY5N9KAyU6TH0ZJuQOmQc=', 'base64')
cipher.encrypt('my value', key)
cipher.decrypt('y3axcNW9eA6ggJNYWotsUQ==:k+YSdJ1MBZct/0bOtQ/zvA==', key)
Hex key
var cipher = require('symmetric-cipher.js');
cipher.encrypt('my value', '3fac1504251a027465981346fb5b0d57d398e4df4a03253a4c7d1926e40e9907', 'hex')
cipher.decrypt('y3axcNW9eA6ggJNYWotsUQ==:k+YSdJ1MBZct/0bOtQ/zvA==', '3fac1504251a027465981346fb5b0d57d398e4df4a03253a4c7d1926e40e9907', 'hex')