libE-AES

Enhanced simultaneous compression + encryption

Installing

Via NPM:

npm install libeaes

This installs a CLI binary accessible with the libeaes command.

# Check if libeaes command has been installed and accessible on your path
$ libeaes -v
v1.2.0

Usage

CLI

The libeaes command, using the algorithm, can perfectly process anything thrown at it. No matter the size. And give useful statistics at the end.

$ libeaes encrypt file.txt outputfile.enc
$ libeaes decrypt outputfile.enc outputfile.dec

# Piping output
$ libeaes encrypt movie.mp4 > movie.enc
# Stream an encrypted file in real time (e.g Watching the movie)
$ libeaes decrypt movie.enc | vlc -

Use --help to see full usage documentation. Use --help on specific commands to see docmentation for that command.

$ libeaes encrypt --help
$ libeaes decrypt --help

The commands can also be shortened to enc and dec respectfully.

$ libeaes enc file.txt output.enc
$ libeaes dec output.enc output.dec

Programmatically

// Node CommonJS
const libeaes = require('libeaes');
// Or ES6
import libeaes from 'libeaes';

Examples

Singular Operation

let password = "#P@$$W0R9";
let encrypted = libeaes.encrypt('Hello world', password);
// Compressed, encrypted content

let decrypted = libeaes.decrypt(encrypted, password);
// "Hello world"

Stream Operation

// Encrypt a stream, pipe output elsewhere
let encryptor = libeaes.EAESEncryptor("#P@$$W0R9");
inputStream.pipe(encryptor).pipe(outputStream);

// Decrypt a stream, pipe output elsewhere
let decryptor = libeaes.EAESDecryptor("#P@$$W0R9");
inputStream.pipe(decryptor).pipe(outputStream);

// Stream sequential encryption and decryption operations
let encryptor = libeaes.EAESEncryptor("#P@$$W0R9");
let decryptor = libeaes.EAESDecryptor("#P@$$W0R9");

inputStream.pipe(encryptor).pipe(decryptor).pipe(outputStream);
// inputStream == outputStream

File Operations

libeaes.encryptFileStream("rawfile.txt", "encryptedfile.txt", "#P@$$W0R9");
libeaes.decryptFileStream("encryptedfile.txt", "decryptedfile.txt", "#P@$$W0R9");

API

libeaes.encrypt(data, key)

• data: <string> | <Buffer>
• key: <string> | <Buffer>
• Returns: <Buffer>

Compress + Encrypt the input data, return the processed data

libeaes.decrypt(data, key)

• data: <string> | <Buffer>
• key: <string> | <Buffer>
• Returns: <Buffer>

Decrypt + Decompress the input data, return the processed data

libeaes.rawencrypt(data, key) *Excluding compression

• data: <string> | <Buffer>
• key: <string> | <Buffer>
• Returns: <Buffer>

Encrypt the input data, return the processed data.

Input data is encrypted without initial compression.

libeaes.rawdecrypt(data, key) *Excluding decompression

• data: <string> | <Buffer>
• key: <string> | <Buffer>
• Returns: <Buffer>

Decrypt raw input data, return the processed data.

Input data is assumed to be uncompressed.

Class: EAESEncryptor(key[, opts]) extends zlib.Gzip

• key: <string> | <Buffer>
• opts: <zlib options>

Create a Transforming EAES Encryptor.

Data piped in here is compressed and encryped with the key configuration.

EAES Streams are encrypted, compressed streams that are tailored to the algorithm in this repo.

The opts object are passed directly into zlib.Gzip

Event: 'error'

• err: <Error>
• code: <number>

This is emitted by either the compression or encryption process.

code is 1 when emitted by the encryption engine and undefined otherwise.

Catch errors explicitly with the 'error:compressor' and 'error:encryptor' events.

Event: 'error:encryptor'

• err: <Error>

The 'error:encryptor' event is emitted if an error occurred while encrypting compressed data. The listener callback is passed a single Error argument when called.

The stream is not closed when the 'error:encryptor' event is emitted.

Event: 'error:compressor'

• err: <Error>

The 'error:compressor' event is emitted if an error occurred while encrypting raw data. The listener callback is passed a single Error argument when called.

The stream is not closed when the 'error:compressor' event is emitted.

Class: EAESDecryptor(key[, opts]) extends zlib.Gunzip

• key: <string> | <Buffer>
• opts: <zlib options>

Create an EAES Decryptor Stream.

Data piped in here is decrypted and decompressed with the key configuration.

EAES Streams are encrypted, compressed streams that are tailored to the algorithm in this repo.

The opts object are passed directly into zlib.Gunzip

Event: 'error'

• err: <Error>
• code: <number>

This is emitted by either the decompression or decryption process.

code is 1 when emitted by the decryption engine and undefined otherwise.

Catch errors explicitly with the 'error:decompressor' and 'error:decryptor' events.

Event: 'error:decryptor'

• err: <Error>

The 'error:decryptor' event is emitted if an error occurred while decrypting decompressed data. The listener callback is passed a single Error argument when called.

The stream is not closed when the 'error:decryptor' event is emitted.

Event: 'error:decompressor'

• err: <Error>

The 'error:decompressor' event is emitted if an error occurred while decrypting raw data. The listener callback is passed a single Error argument when called.

The stream is not closed when the 'error:decompressor' event is emitted.

libeaes.encryptFileStream(infile, outfile, key)

• infile: <string> | <buffer> | <url>
• outfile: <string> | <buffer> | <url>
• key: <string> | <Buffer>
• Returns: <fs.WriteStream>

Read the file, compress and encrypt each chunk, write to the outfile.

Returns the outputfile's stream object.

libeaes.decryptFileStream(infile, outfile, key)

• infile: <string> | <buffer> | <url>
• outfile: <string> | <buffer> | <url>
• key: <string> | <Buffer>
• Returns: <fs.WriteStream>

Read the file, decrypt and decompress each chunk, write to the outfile.

Returns the outputfile's stream object.

ClI Info

• When using pipes, it's not possible to seek through the stream
• To avoid the terminal being cluttered while using pipes, direct other chained binaries (stdout, stderr) to /dev/null

# Watching from an encrypted movie, hiding vlc's log information
$ libeaes dec movie.enc | vlc - > /dev/null 2>&1

Development

Building

Feel free to clone, use in adherance to the license and perhaps send pull requests

git clone https://github.com/miraclx/libeaes-js.git
cd libeaes-js
npm install
# hack on code
npm run build
npm test

Testing

Tests are executed with Jest. To use it, simple run npm install, it will install Jest and its dependencies in your project's node_modules directory followed by npm run build and finally npm test.

To run the tests:

npm install
npm run build
npm test

License

Apache 2.0 © Miraculous Owonubi (@miraclx) <[email protected]>