buffer-aead
TypeScript icon, indicating that this package has built-in type declarations

0.1.0 • Public • Published

buffer-aead

npm package

npm QA

Buffer encryption, using aead (authenticated encryption with associated data), powered by strong crypto algorithms, written in typescrypt

install

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):

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.

Available AEADs

Currently the following aead algorithms are supported

  • AES in Galois Counter Mode
    • with 128 bit key size: import { aes128gcm } from 'buffer-aead'
    • with 192 bit key size: import { aes192gcm } from 'buffer-aead'
    • with 256 bit key size: import { aes256gcm } from 'buffer-aead'
  • 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: import { aes128ccm } from 'buffer-aead'
    • with 192 bit key size: import { aes192ccm } from 'buffer-aead'
    • with 256 bit key size: import { aes256ccm } from 'buffer-aead'
  • AES-256 in CTR (Counter Mode) with HMAC (SHA-256): import { aesctrhmac } from 'buffer-aead' (not recommended)
  • chacha20 with poly1305: import { chacha20poly1305 } from 'buffer-aead'
  • xchacha20 with poly1305: import { xchacha20poly1305 } from 'buffer-aead'

key/nonce generation

To simplify key/nonce generation, force correct length and prevent miss-use, there are two helper functions:

  • keyGen: 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

import { chacha20poly1305 } from 'buffer-aead';
const key = chacha20poly1305.keyGen();
const nonce = chacha20poly1305.nonceGen();

encrypt and decrypt

each aead object (aes256gcm, for example) provides 2 main functions:

  • encrypt
    • takes an EncryptionInput object
    • returns an EncryptionOutput object
  • decrypt
    • takes a DecryptionInput object
    • returns a Buffer

See Inputs/Outputs for details.

Examples, using AES-256-GCM

provide data to encrypt (key and noce will be generated inside encrypt function)
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)
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)
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
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)
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 });

Inputs/Outputs

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:

node-crypto

nodejs provides a native crypto lib. Fast, secure, with great reputation.

@stablelib/xchacha20

@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

Development

install dependencies

npm install

QA

npm run qa

License Check

(reports scss-parser to be incompatible, which is a scss-parser bug, due to invalid License declaration)

npm run licenseCheck

Only Tests

npm run test

Build

npm run build

Release Package on npm

[this should be done by github actions]


License

This project is MIT License
See LICENSE.txt

Package Sidebar

Install

npm i buffer-aead

Weekly Downloads

5

Version

0.1.0

License

MIT

Unpacked Size

86.5 kB

Total Files

77

Last publish

Collaborators

  • tomatencrypt