Encrypting and decrypting your data in chains made easy!
Last updated 7 months ago by michaeldegroot .
MIT · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install cipher-chain 
SYNC missed versions from official npm registry.


HitCount Package quality Build Status Coverage Status Licensing Repo size Downloads per week Node version Help us and star this project

Symmetric encryption and decryption in cipher chains protected by a unique secret strings per chain, Can compress data (zlib), Can encrypt/decrypt files and whole directories. Uses zxcvbn for secret requirements with minimum of 24 characters per secret. encrypt-then-mac authentication.


npm install cipher-chain --save

How it works

- Encrypting

When creating a cipher-chain instance you are presented with some options, First you need to define a secret this is a array and it needs to have the same length as your chain variable. Secrets need to be unique from each other, error will be thrown if not. If enableSecurityRequirements is enabled (default true) then secret(s) need to be min 24 chars and comply to at least a score of 3 from the zxcvbn package.

So secondly you will need to define a chain, this will be the path the encryption/decryption process goes through to get the encrypted and plaintext respectively. chain is a array with strings representing all cipher algorithms names. The cipher algorithm list can be viewed by calling cipherchain.ciphers

When you create a cipher-chain instance the script goes through the chain list and for every algorithm it creates a KDF generated hashed key derived from the secret array corresponding index of the current chain index which is used as the key for that specific encipherment algorithm in the chain.

Then when you call the cipherchain.encrypt, cipherchain.encryptFile(file) or cipherchain.encryptDirectory(directory) function it checks what the chain is and will convert your plaintext to ciphertext via traversal of the chain list.

So if you have a chain value of ['aes-256-gcm', 'aes-192-gcm', 'camellia-256-cbc']

then the encryption process will be:

plaintext -> aes-256-gcm -> aes-192-gcm -> camellia-256-cbc -> ciphertext

and decryption process will be:

ciphertext -> camellia-256-cbc -> aes-192-gcm -> aes-256-gcm -> plaintext

After encryption chain end a hmac is computed of the end resulting ciphertext and before decryption chain start the hmac is compared (timings safe) against the end resulting ciphertext of that decryption process. If it not verifies a error is thrown

For each algorithm encryption chain pass a random initialization vector is generated

- Decrypting

All encrypted strings have the same format and recgonisable by the starting prefix of @CC4- indicating its a cipher-chain encrypted string and its major version 3, so if there are breaking changes because of a major version update in the module, the encrypted ciphertext wont be compatible to decrypt. They can look like this:


or if compressData option is set to true:


If you look closely you can see : being delimiters which will have the following result when split:

first the @CC4- is removed internally when decrypting the string


The mapping for this format is as followed:


So we can conclude we have the following data when decrypting the string:

const data = {
	hmac: '56832c1b9e806bc1164523ba86925707a3ba6eb59716ae3c148426a036967f9469bb73a7cdd038969b6172098465ea33e97de072ba112112cf46f00ecf31dd40',
	authTag: '80c0b153a3f83b34b481c3e5843c2c9c',
	kdfSalt: '038bb16ebbd0bdcecec2d82b',
	initializationVector: '53b04561ea178266f146b52f7dd1e07386f5c95bf1efad75f06bbbbc702ea0b8',
	encryptedData: '0ed43ae8'

Cipher-chain knows internally which algorithm cipher to use for this to decrypt your strings. The only piece of the puzzle here to decrypt the encryptedData variable is if we know the secret kdf hash for that specific chain


const CipherChain = require('cipher-chain')

const aAsyncFunction = async () => {
	const options = {} // default options
	const cipherchain = await new CipherChain(options)


Argument Explanation Default
secret The secret(s) to use for specific chains, needs to be a array and as long as your chain option undefined
chain Array with strings that hold the cipher algorithms you want to use as a path to traverse from plain to cipher and vice versa undefined
autoPadding Boolean to switch auto padding for the cipher. true
timingSafeCheck Boolean for function equal check for hmac based on a constant-time algorithm without leaking timing information that would allow an attacker to guess one of the values. true
compressData Boolean to compress end result after encryption to save data space, works for all encrypt functions true
concurrentFiles How many concurrent files will be encrypted and decrypted at any given time. 20
enableSecurityRequirements Enables the zxcvbn package and min 24 char secret(s) requirements for extra security. true
hmacAlgorithm String for what algorith the hmac verify should use. sha512
kdf See Below See Below
 // const argon2 = require('argon2')
    use: 'argon2', // or blake2, scrypt, pbkdf2,
    saltLength: 12, // salt length for the kdf, bigger value means bigger ciphertext data, especially with multiple chain encrypts
    options: {
      argon2: { // some argon2 setings you could do
        type: argon2.argon2i,
        memoryCost: 1024 * 8,
        timeCost: 6
      pbkdf2: { // some pbkdf2 setings you could do, since 'use' in options is set to 'argon2' this is obsolete
        rounds: 10000,
        hash: 'sha512'



Gets a list of all available ciphers to work with


Gets a list of all available KDFs to work with


Encrypts a plaintext to a ciphertext

let encrypted = await cipherchain.encrypt('secret data')


Decrypts a ciphertext to a plaintext

let decrypted = await cipherchain.decrypt(encrypted)


Encrypts a file, also hashes filename

const newFilename = await cipherchain.encryptFile(path.join('../', 'encryptme.txt'))


Decrypts a file

await cipherchain.decryptFile(path.join('../', 'encryptme.txt'))


Encrypts a directory, also hashes filenames

await cipherchain.encryptDirectory(path.join('../', 'encryptme'))


Decrypts a directory

await cipherchain.decryptDirectory(path.join('../', 'encryptme'))


const CipherChain = require('cipher-chain')

const start = async () => {
	const cipherchain = await new CipherChain({
		chain: ['aes-256-gcm', 'blowfish', 'camellia-256-cbc'],
		kdf: {
			use: 'argon2', // or blake2, scrypt, pbkdf2,
			saltLength: 12, // salt length for the kdf, bigger value means bigger ciphertext data, especially with multiple chain encrypts
			options: {
				argon2: { // some argon2 setings you could do
					type: argon2.argon2i,
					memoryCost: 1024 * 8,
					timeCost: 6
				pbkdf2: { // some pbkdf2 setings you could do, since 'use' in options is set to 'argon2' this is obsolete
					rounds: 10000,
					hash: 'sha512'

	const ciphers = cipherchain.ciphers // List of cipher algorithms to use in your chain
	const kdfs = cipherchain.kdfs // List of KDFs (key derivation function) to use

	// Encrypt/decrypt a string
	const ciphertext = await cipherchain.encrypt('encrypt this')
	const plaintext = await cipherchain.decrypt(ciphertext)

	// Encrypt/decrypt a file
	const newFilename = await cipherchain.encryptFile('./file.txt')
	await cipherchain.decryptFile(newFilename)

	// Encrypt/decrypt a directory
	await cipherchain.encryptDirectory('./directory')
	await cipherchain.decryptDirectory('./directory')



Copyright (c) 2020 by GiveMeAllYourCats. Some rights reserved.
cipher-chain is licensed under the MIT License as stated in the LICENSE file.

Current Tags

  • 4.0.1                                ...           latest (7 months ago)

9 Versions

  • 4.0.1                                ...           7 months ago
  • 4.0.0                                ...           7 months ago
  • 3.0.0                                ...           7 months ago
  • 1.0.6                                ...           7 months ago
  • 1.0.4                                ...           7 months ago
  • 1.0.3                                ...           7 months ago
  • 1.0.2                                ...           7 months ago
  • 1.0.1                                ...           7 months ago
  • 1.0.0                                ...           7 months ago
Maintainers (1)
Today 0
This Week 0
This Month 0
Last Day 0
Last Week 0
Last Month 0
Dependencies (8)
Dev Dependencies (13)
Dependents (0)

Copyright 2014 - 2016 © |