perry-mitchell / Iocane
Programming Languages
Projects that are alternatives of or similar to Iocane
A powerful and easy-to-use text and data encryption library for NodeJS and the web.
About
iocane makes text and data encryption and decryption easy by bundling all the complicated processes into one succinct library. Encrypt and decrypt strings and buffers easily by using iocane's encryption format - string->string / buffer->buffer.
This library uses "sessions" for encryption and decryption. A session describes one encryption/decryption action, and can also have options be further overridden at the time of execution. Check the examples below for a better idea of how this process works.
iocane works in the browser, too. Both a node version and a web version are available:
const iocane = require("iocane"); // node
import * as iocane from "iocane/web" // web
Features
iocane by default boasts the following features:
- AES-CBC / AES-GCM encryption
- 256bit keys
- PBKDF2 key derivation (with 250k iterations)
- ~14kb minified web version
Installation
Install iocane
as a dependency using npm
:
npm install iocane --save
Usage
iocane can be easily used to encrypt text:
const { createSession } = require("iocane");
createSession()
.encrypt("some secret text", "myPassword")
.then(encryptedString => {
// do something with the encrypted text
});
Decryption is even simpler, as instructions on how to decrypt the payload is included in the payload itself:
createSession()
.decrypt(encryptedString, "myPassword")
.then(decryptedString => {
// ...
});
During encryption, you can override a variety of options:
createSession()
.use("gcm") // use GCM encryption
.setDerivationRounds(300000)
.encrypt(target, password);
Each cryptographic function can be overridden:
createSession()
.overrideDecryption("cbc", cbcDecFn)
.overrideDecryption("gcm", gcmDecFn)
.overrideEncryption("cbc", cbcEncFn)
.overrideEncryption("gcm", gcmEncFn)
.overrideIVGeneration(genIV)
.overrideKeyDerivation(deriveKey)
.overridePBKDF2(pbkdf2)
.overrideSaltGeneration(genSalt)
.encrypt(/* ... */);
Note that the default encryption mode is "cbc"
(AES-CBC encryption).
overrideKeyDerivation
and overridePBKDF2
do two very different things. overrideKeyDerivation
wraps overridePBKDF2
, so most of the time you'll most likely just want overridePBKDF2
if you want to change the PBKDF2 implementation.
You can check out the API documentation for more information.
Encrypting and decrypting data buffers
Iocane can handle buffers the same way it handles strings - just pass them into the same encrypt/decrypt functions:
const iocane = require("iocane");
const fs = require("fs");
createSession()
.use("cbc")
.encrypt(fs.readFileSync("./test.bin"), "passw0rd")
.then(data => fs.writeFileSync("./test.bin.enc", data));
The same can be performed on the web, with array buffers in place of standard buffers.
Web usage
When building a project for the web, make sure to use the web-based version of iocane. Bundling the node version will create super-large bundles and result in slow encryption and decryption. iocane for the web uses UMD so it can be imported or simply loaded straight in the browser as a <script>
.
If you load iocane directly in the browser, it will create a global namespace at window.iocane
(eg. window.iocane.createSession
).
Supported environments
iocane supports NodeJS version 10 and above. Node 8 was supported in 3.x
and versions prior to 8 were supported in 1.x
.
iocane is used in the browser as well - it works everywhere that SubtleCrypto
, ArrayBuffer
and Promise
are available.
Note: iocane is written in TypeScript, though versions before v2 where written in JavaScript.
Buttercup
iocane was originally part of the Buttercup suite. Buttercup is a supported dependent of iocane and efforts are made to align iocane with Buttercup's target platforms and uses.