Buffer encryption, using aead (authenticated encryption with associated data), powered by strong crypto algorithms.
npm install buffer-aead
 
Buffer encryption, using aead (authenticated encryption with associated data), powered by strong crypto algorithms, written in typescrypt
shell
npm i buffer-aead
`___
Supported aead algorithms/suites
* AES-256-CTR with HMAC-SHA256 (not recommended)
* AES-GCM
* AES-CCM (plaintext limited to be less than 64 KiB)
* ChaCha20-Poly1305
* XChaCha20-Poly1305___
Quick example (AES-256-GCM):
js
import { aes256Gcm } from 'buffer-aead'
const { key, nonce, ciphertext, authTag } = aes256Gcm.encrypt({ data });
const decrypted = aes256Gcm.decrypt({ key, nonce, ciphertext, authTag });
`___
Usage
Detailed How-To with examples.$3
Currently the following aead algorithms are supported* AES in Galois Counter Mode
* with 128 bit key size:
* with 192 bit key size:
* with 256 bit key size:
* AES in CCM (Counter Mode with CBC-Mac)
Important: For this AEAD the plaintext is limtted to be less than 64 KiB (65536 bytes)
* with 128 bit key size:
* with 192 bit key size:
* with 256 bit key size:
* AES-256 in CTR (Counter Mode) with HMAC (SHA-256): (not recommended)
* chacha20 with poly1305: import { chacha20poly1305 } from 'buffer-aead'
* xchacha20 with poly1305: $3
To simplify key/nonce generation, force correct length and prevent miss-use, there are two helper functions:
* : Returns a key, appropriate to the particular AEAD
* nonceGen: Returns a nonce (number only used once, aka IV (Initial Vector)), appropriate to the particular AEAD#### Example, using chacha20-poly1305
`js
import { chacha20poly1305 } from 'buffer-aead';
const key = chacha20poly1305.keyGen();
const nonce = chacha20poly1305.nonceGen();
`$3
each aead object (aes256gcm, for example) provides 2 main functions:
*
* takes an object
* returns an EncryptionOutput object
* decrypt
* takes a object
* returns a BufferSee Inputs/Outputs for details.
#### Examples, using AES-256-GCM
##### provide data to encrypt (key and noce will be generated inside encrypt function)
js
import { aes256gcm } from 'buffer-aead';
const data = Buffer.from('example buffer to encrypt', 'utf8');
const { key, nonce, ciphertext, authTag } = aes256gcm.encrypt({ data });
const decrypted = aes256gcm.decrypt({ key, nonce, ciphertext, authTag });
`##### provide data and key (nonce will be generated inside encrypt function)
js
import { aes256gcm } from 'buffer-aead';
const data = Buffer.from('example buffer to encrypt', 'utf8');
const key = aes256gcm.keyGen();
const { nonce, ciphertext, authTag } = aes256gcm.encrypt({ data, key });
const decrypted = aes256gcm.decrypt({ key, nonce, ciphertext, authTag });
`##### provide data and nonce (key will be generated inside encrypt function)
js
import { aes256gcm } from 'buffer-aead';
const data = Buffer.from('example buffer to encrypt', 'utf8');
const nonce = aes256gcm.nonceGen();
const { key, ciphertext, authTag } = aes256gcm.encrypt({ data, nonce });
const decrypted = aes256gcm.decrypt({ key, nonce, ciphertext, authTag });
`##### provide data, key and nonce
js
import { aes256gcm } from 'buffer-aead';
const data = Buffer.from('example buffer to encrypt', 'utf8');
const key = aes256gcm.keyGen();
const nonce = aes256gcm.nonceGen();
const { ciphertext, authTag } = aes256gcm.encrypt({ data, key, nonce });
const decrypted = aes256gcm.decrypt({ key, nonce, ciphertext, authTag });
`##### provide all including additional data (associated data)
js
import { aes256gcm } from 'buffer-aead';
const data = Buffer.from('example buffer to encrypt', 'utf8');
const key = aes256gcm.keyGen();
const nonce = aes256gcm.nonceGen();
const additionData = Buffer.from('Additional data that is taken into account when generating the MAC.', 'utf8');
const { ciphertext, authTag } = aes256gcm.encrypt({ data, key, nonce, additionalData });// also fails, if additionalData is not like it was given to encrypt function
const decrypted = aes256gcm.decrypt({ key, nonce, ciphertext, authTag, additionalData });
`$3
#### Buffer
nodejs Buffer with various lengths
#### EncryptionInput (typescript notation,
means optional)
* data: Buffer
* key?: Buffer
* nonce?: Buffer
* additionalData?: Buffer#### EncryptionOutput (typescript notation)
*
key: Buffer
* nonce: Buffer
* ciphertext: Buffer
* authTag: Buffer#### DecryptionInput (typescript notation,
? means optional)
* key: Buffer
* nonce: Buffer
* ciphertext: Buffer
* authTag: Buffer
* additionalData?: Buffer___
Used crypto libraries
This package uses the following libraries for it's cryptography:$3
nodejs provides a native crypto lib. Fast, secure, with great reputation.$3
@stablelib/xchacha20 provides ready to use xchacha20, but we only use hchacha from it,
which is required to build xchacha20-poly1305 upon node-crypto's chacha20-poly1305. \
@stablelib/xchacha20's hchacha implementation works and it is hard (if not imposiible) to implement hchacha working but insecure and therefore it seems viable to use.___
Further readings
* nodejs crypto api: https://nodejs.org/api/crypto.html
* AEAD: https://en.wikipedia.org/wiki/Authenticated_encryption
* AES: https://en.wikipedia.org/wiki/Advanced_Encryption_Standard
* GCM: https://en.wikipedia.org/wiki/Galois/Counter_Mode
* CCM: https://en.wikipedia.org/wiki/CCM_mode
* CTR: https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Counter_(CTR)
* HMAC: https://en.wikipedia.org/wiki/HMAC
* SHA256: https://en.wikipedia.org/wiki/SHA-2
* chacha20-poly1305: https://en.wikipedia.org/wiki/ChaCha20-Poly1305
* xchacha20: https://libsodium.gitbook.io/doc/advanced/stream_ciphers/xchacha20Development
$3
`sh
npm install
`$3
shell
npm run qa
`$3
(reports to be incompatible, which is a scss-parser bug, due to invalid License declaration)
`shell
npm run licenseCheck
`$3
shell
npm run test
`$3
shell
npm run build
`$3
___