A fast, native, cryptographic engine for the web
npm install @cubbit/enigmaA fast, native, environment-agnostic, cryptographic engine for the web
``ts
import Enigma from '@cubbit/enigma';
new Enigma.AES().init().then(async (aes: Enigma.AES) =>
{
const my_secret = 'My secret';
const cipher = await aes.encrypt(my_secret);
console.log(cipher);
});
/*
{
content:
tag:
iv:
}
*/
`
Enigma is a crypto library available both for Node.js platform and for the Web. It relies on OpenSSL to provide the most common cryptographical utilities. In a web environment, Enigma leverages on a WebAssembly-compiled version of OpenSSL to boost performances.
Enigma is a npm module available through the npm registry.
Installation is done both in Node.js and in a web environment using the npm install command:
`bash`
npm install @cubbit/enigma
If you want to work from source, just clone the repo and run the install script as:
`bash`
git clone https://github.com/cubbit/enigma.git
cd enigma
npm install
Before installing, download and install Node.js. Node.js version 8.0 or higher is required (Node.js 11 has not been tested yet).
Enigma is supported on the following platforms.
| | x86 | x64 | arm32 | arm64 |
| ------- | ------ | --- | ----- | ----- |
| Linux | ︎︎︎ ✔︎ | ✔︎ | ✔︎ | ✔︎ |
| macOS | - | ✔︎ | - | ✔︎ |
| Windows | ✔︎ | ✔︎ | - | - |
After installing just import @cubbit/enigma in your code and you are ready to go.
Install the library by following the Installation section. Then, just import @cubbit/enigma in your source and use it as you would do on Node.js.
Important: Enigma needs a Buffer polyfill in order to work correctly on the web. The default one provided by webpack is ok. Otherwise you'll need to provide one by yourself.
Enigma includes the following cryptographical utilities:
- Hashing algorithms (SHA256)
- Simmetric encryption algorithms (AES256)
- Asymmetric encryption algorithms (RSA), ECC)
- Misc utilities (DiffieHellman key exchange, Random, Key derivation algorithms)
Please refer to the API section to discover more about how to use each of them
`ts
import Enigma from '@cubbit/enigma';
const message = 'Hello world';
const hash = Enigma.Hash.digest(message);
console.log(hash); // A591A6D40BF420404A011733CFB7B190D62C65BF0BCDA32B57B277D9AD9F146E
`
`ts
import Enigma from '@cubbit/enigma';
new Enigma.AES().init().then(async (aes: Enigma.AES) =>
{
const my_secret = 'My secret';
const cipher = await aes.encrypt(my_secret);
console.log(cipher);
});
/*
{
content:
tag:
iv:
}
*/
`
When encrypting a big file you may encounter browser limitations or memory issues. The AES stream class is design to overcome these problems.
`ts
// On Node.js
import {createReadStream} from 'fs';
import Enigma from '@cubbit/enigma';
const file_stream = fs.createReadStream('my_secret_image.png');
new Enigma.AES().init().then((aes: Enigma.AES) =>
{
const iv = Enigma.Random.bytes(16);
const aes_stream = aes.encrypt_stream(iv);
aes_stream.once('finish', () => console.log('File encrypted'));
file_stream.pipe(aes_stream);
});
// On the Web
import Enigma from '@cubbit/enigma';
import WebFileStream from '@cubbit/web-file-stream';
const file = new File(); // You can get this File object through an file input tag
const file_stream = WebFileStream.create_read_stream(file);
new Enigma.AES().init().then((aes: Enigma.AES) =>
{
const iv = Enigma.Random.bytes(16);
const aes_stream = aes.encrypt_stream(iv);
aes_stream.once('finish', () => console.log('File encrypted'));
file_stream.pipe(aes_stream);
});
`
`ts
import Enigma from '@cubbit/enigma';
const existing_key = /.../
const aes = new Enigma.AES().init({key: existing_key}).then(async (aes: Enigma.AES =>
{
const message = aes.decrypt(my_secret).toString();
console.log(message); // "My secret"
});
`
`ts
import Enigma from '@cubbit/enigma';
const keypair = Enigma.RSA.create_keypair();
`
`ts
import Enigma from '@cubbit/enigma';
const message = 'My secret';
new Enigma.RSA().init().then(async (rsa: Enigma.RSA) =>
{
const encrypted = await Enigma.RSA.encrypt(message, rsa.keypair.public_key);
console.log(encrypted);
/*
*/
const decrypted = (await rsa.decrypt(encrypted)).toString();
console.log(decrypted); // "My secret"
});
`
`ts
import Enigma from '@cubbit/enigma';
const keypair = Enigma.ED25519.create_keypair();
`
`ts
import Enigma from '@cubbit/enigma';
const message = 'To be signed';
const ecc = new Enigma.ED25519();
const signature = ecc.sign(message);
Enigma.ED25519.verify(message, ecc.keypair.public_key, signature).then(console.log) // true
`
`ts
import Enigma from '@cubbit/enigma';
const message = 'Original message';
const salted_key = await Enigma.KeyDerivation.pbkdf2(message);
`
`ts
import Enigma from '@cubbit/enigma';
const object = {message: 'To be signed'};
const ecc = new Enigma.ED25519();
const contract = Enigma.Attorney.redact(object, ecc);
const is_valid = Enigma.Attorney.verify(contract, ecc.keypair.public_key);
console.log(is_valid); // true
`
`ts
import Enigma from '@cubbit/enigma';
Enigma.init().then(async () =>
{
const random_int4 = Enigma.Random.integer(32);
const random_bytes = Enigma.Random.bytes(32);
});
`
A class which permits a DiffieHellman key echange based on elliptic curves.
Elliptic curve adopted is NID_X9_62_prime256v1.
- initialize(): void: generate the key pairs.get_public_key(): string
- : returns the public key as a string having these properties: _PEM_ format; uncompressed; ASN.1 standard form called _NAMED CURVE_.derive_secret(endpoint_public_key: string): string
- : needs a public key in the same format described above and returns the secret as a string in hex format.
`ts
import Enigma from '@cubbit/enigma';
Enigma.init().then(async () =>
{
const dh = new Enigma.DiffieHellman();
dh.initialize();
const public_key: string = dh.get_public_key();
// receive public key from remote endpoint
// send my public key to remote endpoint
const shared_secret: string = await dh.derive_secret(endpoint_public_key);
});
`
To build the project's bindings just run the following command after cloning the repository:
`bash`
npm run build
npm run build:web
- perl required to build OpenSSL on Windows
- docker required for the web build
To run the test suite, first install the dependencies, then run npm test:
`bash``
npm install
npm test
Feel free to open an issue or a pull request to report bugs and suggest new features. Please refer to our Contributions guidelines for more details about the contribution process.