aead-stream

Authenticated encryption on arbitrary large files

aead-stream is a simple API to perform authenticated symmetric encrytion on data of arbitrary size.

Install

npm install aead-stream

Usage

encrypt(key, plaintext[, options])

• key <Uint8Array> the symmetric key used to encrypt the data
• plaintext <AsyncIterable<Uint8Array>> a stream of Uint8Arrays with the plaintext data
• options <Object> Default: default options
  • algorithm <string> a valid algorithm for crypto.createCipheriv
  • nonceLength <number> the length of generated nonces in bytes
  • authTagLength <number> the length of the authentication tag
  • chunkSize <number> the size of a ciphertext chunk (including nonce and authentication tag)
  • associatedData <Uint8Array> optional additional data to be used for authentication tag calculation
• Returns: <AsyncIterable<Uint8Array>> a stream of Uint8Arrays with the ciphertext data

Click to view example

const { encrypt } = require("aead-stream");
const { createReadStream } = require("fs");

/**
 * @param {Uint8Array} key 256 bit key material
 * @param {string} filepath a file path
 */
async function encyptFile(key, filepath) {
  const readStream = createReadStream(filepath);

  for await (const encryptedChunk of encrypt(key, readStream)) {
    // store encryptedChunk - it is a Uint8Array with at most 64K size
  }
}

decrypt(key, ciphertext[, options])

• key <Uint8Array> the symmetric key used to encrypt the data
• ciphertext <AsyncIterable<Uint8Array>> a stream of Uint8Arrays with the ciphertext data
• options <Object> Default: default options
  • algorithm <string> a valid algorithm for crypto.createCipheriv
  • nonceLength <number> the length of nonces in bytes
  • authTagLength <number> the length of the authentication tag
  • chunkSize <number> the size of a ciphertext chunk (including nonce and authentication tag)
  • associatedData <Uint8Array> optional additional data to be used for authentication tag calculation
• Returns: <AsyncIterable<Uint8Array>> a stream of Uint8Arrays with the plaintext data

Click to view example

const { decrypt } = require("aead-stream");
const { createReadStream } = require("fs");

/**
 * @param {Uint8Array} key 256 bit key material
 * @param {string} filepath a file path to an encrypted file
 */
async function decyptFile(key, filepath) {
  const readStream = createReadStream(filepath);

  for await (const plain of decrypt(key, readStream)) {
    // process plain - a Uint8Array
  }
}

Default options

• algorithm "chacha20-poly1305",
• nonceLength 12,
• authTagLength 16,
• chunkSize 64 * 1024 (64K)