Crypto Cipher 🔐

Node.js Cipher cryptograph utility library

Getting started

The crypto-cipher library provides AES encryption and decryption functionality, supporting both in-memory buffers and streams. It adheres to the NIST SP 800-38D standard recommendations.

⚠️ Note that every performed operation cannot be accomplished client-side and must be executed on a back-end server.

It is part of the crypto utility libraries and can be installed by running the following command:

npm i @alessiofrittoli/crypto-cipher

or using pnpm

pnpm i @alessiofrittoli/crypto-cipher

Key features

Supports multiple AES algorithms (CCM, GCM, OCB, CBC) and even chacha20-poly1305.
In-memory buffer encryption and decrpytion.
Robust support for encrypting and decrypting streams (in-memory and file based).
Hybrid encryption methods for combining symmetric and asymmetric cryptography.

Security Considerations

Random salt and IV generation.
AEAD - Authenticated encryption modes with proper authTag and Additional Authenticated Data handling.

Readable and Modular

Separation of concerns with clear method responsibilities.
Comprehensive JSDoc comments enhance maintainability and readability.

What's Changed

🎉 Core updates in the latest release:

Cipher methods have been refactored to provide a solid and easy usage
Cipher.HybridEncrypt() and Cipher.HybridDecrypt() have been added. These methods will allow you to encrypt/decrypt in-memory buffer data using hybrid encryption algorithms.
Cipher.stream subgroup has been added to keep method names consistent across the library.
hybrid encryption doesn't require a password anymore which was redundant. an RSA key pair is all what you need.
providing RSA key length during hybrid decryption is no longer needed.

Migration guide

Migrating from v2.x.x to v3.0.0

Cipher.encrypt()

Is now renamed to Cipher.Encrypt(). It's API implementation remain the same.

Cipher.decrypt()

Is now renamed to Cipher.Decrypt(). It's API implementation remain the same.

Cipher.streamEncrypt()

Before

await Cipher.streamEncrypt(password, { input, output }).encrypt();

Now

await Cipher.stream.Encrypt(password, { input, output });

Cipher.streamDecrypt()

Before

const { decrypt } = await Cipher.streamDecrypt(password, { input, output });

await decrypt();

Now

await Cipher.stream.Decrypt(password, { input, output });

Cipher.hybridEncrypt()

Before

const { encrypt } = Cipher.hybridEncrypt(
  password,
  {
    key: keyPair.publicKey,
    padding: crypto.constants.RSA_PKCS1_OAEP_PADDING,
    oaepHash: "SHA-256",
  },
  { input, output }
);
await encrypt();

Now

await Cipher.stream.HybridEncrypt(keyPair.publicKey, { input, output });

Cipher.hybridDecrypt()

Before

const { decrypt } = await Cipher.hybridDecrypt(
  {
    key: keyPair.privateKey,
    passphrase: passphrase,
    padding: crypto.constants.RSA_PKCS1_OAEP_PADDING,
    oaepHash: "SHA-256",
  },
  { input, output, rsaKeyLength }
);

await decrypt();

Now

await Cipher.stream.HybridDecrypt(
  { key: keyPair.privateKey, passphrase },
  { input, output }
);

Or even

await Cipher.stream.HybridDecrypt(keyPair.privateKey, { input, output });

API Reference

Constants

`Cipher.SALT_LENGTH`

Defines the minimum, maximum, and default lengths for salt.

Properties

Property	Value
`min`	16
`max`	64
`default`	32

`Cipher.IV_LENGTH`

Defines the minimum, maximum, and default lengths for initialization vectors (IV).

Properties

Property	Value
`min`	8
`max`	32
`default`	16

`Cipher.AUTH_TAG_LENGTH`

Defines the minimum, maximum, and default lengths for authentication tags.

Properties

Property	Value
`min`	4
`max`	16
`default`	16

`Cipher.AAD_LENGTH`

Defines the minimum, maximum, and default lengths for additional authenticated data (AAD).

Properties

Property	Value
`min`	16
`max`	4096
`default`	32

`Cipher.DEFAULT_ALGORITHM`

Specifies default AES algorithms for buffer and stream operations.

Properties

Operation	Algorithm	Description
`buffer`	`aes-256-gcm`	Default algorithm used for buffer data encryption/decryption
`stream`	`aes-256-cbc`	Default algorithm used for stream encryption/decryption (Cipher Block Chaining mode).

`Cipher.ALGORITHM`

An object defining algorithm names.

Properties

Property	Value
`AES_128_CBC`	'aes-128-cbc'
`AES_192_CBC`	'aes-192-cbc'
`AES_256_CBC`	'aes-256-cbc'
`AES_128_CCM`	'aes-128-ccm'
`AES_192_CCM`	'aes-192-ccm'
`AES_256_CCM`	'aes-256-ccm'
`AES_128_GCM`	'aes-128-gcm'
`AES_192_GCM`	'aes-192-gcm'
`AES_256_GCM`	'aes-256-gcm'
`AES_128_OCB`	'aes-128-ocb'
`AES_192_OCB`	'aes-192-ocb'
`AES_256_OCB`	'aes-256-ocb'
`CHACHA_20_POLY`	'chacha20-poly1305'

`Cipher.ALGORITHMS`

An array of supported AES algorithms. This array includes all values in Cipher.ALGORITHM constant.

Methods

`Cipher.Encrypt()`

Encrypts an in-memory data buffer.

Warning

This is not suitable for large data encryption. Use Cipher.stream.Encrypt() or Cipher.stream.HybridEncrypt() methods for large data encryption.

Parameters

Name	Type	Description
`data`	`CoerceToUint8ArrayInput`	Data to encrypt.
`secret`	`CoerceToUint8ArrayInput`	Secret key for encryption.
`options`	`Cph.Options`	(Optional) Additional encryption options.

Returns

Type: Buffer

The encrypted result buffer.

See CoerceToUint8ArrayInput for more informations about supported input data types.
See Cph.Options for more informations about additional encryption options.
See In-memory data buffer encryption/decryption examples.

`Cipher.Decrypt()`

Decrypts an in-memory data buffer.

Warning

This is not suitable for large data decryption. Use Cipher.stream.Decrypt() or Cipher.stream.HybridDecrypt() methods for large data decryption.

Parameters

Name	Type	Description
`data`	`CoerceToUint8ArrayInput`	Data to decrypt.
`secret`	`CoerceToUint8ArrayInput`	Secret key for decryption.
`options`	`Cph.Options`	(Optional) Decryption options (must match encryption).

Returns

Type: Buffer

The decrypted result buffer.

See CoerceToUint8ArrayInput for more informations about supported input data types.
See Cph.Options for more informations about additional decryption options.
See In-memory data buffer encryption/decryption examples.

`Cipher.HybridEncrypt()`

Encrypts in-memory data using hybrid encryption.

Warning

This is not suitable for large data encryption. Use Cipher.stream.HybridEncrypt() method for large data encryption.

Warning

Please, note that when using hybrid encryption/decryption algorithms:

an RSA keypair is required.
if a passphrase is set for the Private Key, please make sure to use one of the Cipher Block Chaining algorithm or chacha20-poly1305 algorithm:
- aes-128-cbc (type can be pkcs1 or pkcs8)
- aes-192-cbc (type can be pkcs1 or pkcs8)
- aes-256-cbc (type can be pkcs1 or pkcs8)
- chacha20-poly1305 (type can only be pkcs1)

Parameters

Parameter	Type	Default	Description
`data`	`CoerceToUint8ArrayInput`	-	The data to encrypt.
`key`	`crypto.KeyLike`	-	The RSA Public Key.
`options`	`Cph.Options`	-	(Optional) Additional options.

Returns

Type: Buffer

The encrypted result buffer.

See CoerceToUint8ArrayInput for more informations about supported input data types.
See Cph.Options for more informations about additional decryption options.
See In-memory data buffer hybrid encryption/decryption example.

`Cipher.HybridDecrypt()`

Decrypts in-memory data using hybrid encryption.

Warning

This is not suitable for large data decryption. Use Cipher.stream.HybridDecrypt() method for large data decryption.

Warning

Please, note that when using hybrid encryption/decryption algorithms:

an RSA keypair is required.
if a passphrase is set for the Private Key, please make sure to use one of the Cipher Block Chaining algorithm or chacha20-poly1305 algorithm:
- aes-128-cbc (type can be pkcs1 or pkcs8)
- aes-192-cbc (type can be pkcs1 or pkcs8)
- aes-256-cbc (type can be pkcs1 or pkcs8)
- chacha20-poly1305 (type can only be pkcs1)

Parameters

Parameter	Type	Default	Description
`data`	`CoerceToUint8ArrayInput`	-	The data to encrypt.
`key`	`Cph.PrivateKey`	-	The RSA Private Key.
`options`	`Cph.Options`	-	(Optional) Additional options.

Returns

Type: Buffer.

The encrypted result Buffer.

See CoerceToUint8ArrayInput for more informations about supported input data types.
See Cph.PrivateKey for accepted formats.
See Cph.Options for more informations about additional decryption options.
See In-memory data buffer hybrid encryption/decryption example.

`Cipher.stream.Encrypt()`

Encrypt stream data.

Parameters

Name	Type	Default	Description
`secret`	`CoerceToUint8ArrayInput`	-	The secret key used to encrypt the data.
`options`	`Cph.Stream.EncryptOptions`	-	An object defining required options.
`options.input`	`Readable`	-	The `Readable` Stream where raw data to encrypt is read.
`options.output`	`Writable`	-	The `Writable` Stream where encrypted data is written.
`options.algorithm`	`Cph.CBCTypes`	`aes-256-cbc`	One of the Cipher Block Chaining algorithm.

Returns

Type: Promise<void>

A new Promise that resolves void once stream encryption is completed.

See In-memory data stream encryption/decryption example.

`Cipher.stream.Decrypt()`

Decrypt stream data.

Parameters

Name	Type	Default	Description
`secret`	`CoerceToUint8ArrayInput`	-	The secret key used to decrypt the data.
`options`	`Cph.Stream.DecryptOptions`	-	An object defining required options.
`options.input`	`Readable`	-	The `Readable` Stream where encrypted data is read.
`options.output`	`Writable`	-	The `Writable` Stream where decrypted data is written.
`options.algorithm`	`Cph.CBCTypes`	`aes-256-cbc`	One of the Cipher Block Chaining algorithm.

Returns

Type: Promise<void>

A new Promise that resolves void once stream decryption is completed.

See In-memory data stream encryption/decryption example.

`Cipher.stream.HybridEncrypt()`

Encrypt stream data using hybrid encryption.

Warning

Please, note that when using hybrid encryption/decryption algorithms:

an RSA keypair is required.
if a passphrase is set for the Private Key, please make sure to use one of the Cipher Block Chaining algorithm or chacha20-poly1305 algorithm:
- aes-128-cbc (type can be pkcs1 or pkcs8)
- aes-192-cbc (type can be pkcs1 or pkcs8)
- aes-256-cbc (type can be pkcs1 or pkcs8)
- chacha20-poly1305 (type can only be pkcs1)

Parameters

Parameter	Type	Default	Description
`key`	`crypto.KeyLike`	-	The RSA Public Key.
`options`	`Cph.Stream.EncryptOptions`	-	An object defining required options.
`options.input`	`Readable`	-	The `Readable` Stream where raw data to encrypt is read.
`options.output`	`Writable`	-	The `Writable` Stream where encrypted data is written.
`options.algorithm`	`Cph.CBCTypes`	`aes-256-cbc`	One of the Cipher Block Chaining algorithm.

Returns

Type: Promise<void>

A new Promise that resolves void once stream encryption is completed.

See In-memory data stream with hybrid encryption/decryption example.

`Cipher.stream.HybridDecrypt()`

Decrypt stream data using hybrid decryption.

Warning

Please, note that when using hybrid encryption/decryption algorithms:

an RSA keypair is required.
if a passphrase is set for the Private Key, please make sure to use one of the Cipher Block Chaining algorithm or chacha20-poly1305 algorithm:
- aes-128-cbc (type can be pkcs1 or pkcs8)
- aes-192-cbc (type can be pkcs1 or pkcs8)
- aes-256-cbc (type can be pkcs1 or pkcs8)
- chacha20-poly1305 (type can only be pkcs1)

Parameters

Parameter	Type	Default	Description
`key`	`Cph.PrivateKey`	-	The RSA Private Key.
`options`	`Cph.Stream.DecryptOptions`	-	An object defining required options.
`options.input`	`Readable`	-	The `Readable` Stream where encrypted data is read.
`options.output`	`Writable`	-	The `Writable` Stream where decrypted data is written.
`options.algorithm`	`Cph.CBCTypes`	`aes-256-cbc`	One of the Cipher Block Chaining algorithm.

Returns

Type: Promise<void>

A new Promise that resolves void once stream encryption is completed.

See CoerceToUint8ArrayInput for more informations about supported input data types.
See Cph.PrivateKey for accepted formats.
See In-memory data stream with hybrid encryption/decryption example.

Types

`CoerceToUint8ArrayInput`

This module supports different input data types and it uses the coerceToUint8Array utility function from @alessiofrittoli/crypto-buffer to convert it to a Uint8Array.

See coerceToUint8Array for more informations about the supported input types.

`Cph.CBCTypes`

AES Cipher Block Chaining algorithms.

`Cph.AesAlgorithm`

All supported AES algorithms.

`Cph.Options<T>`

Common options in encryption/decryption processes.

Type parameters

Parameter	Default	Description
`T`	`Cph.AesAlgorithm`	Accepted algorithm in `Cph.Options`. This is usefull to constraint specifc algorithms.

Properties

Property	Type	Default	Description
`algorithm`	`T`	`aes-256-gcm \| aes-256-cbc`	Accepted algorithms.
`salt`	`number`	`32`	The `salt` length in bytes. Minimum: `16`, Maximum: `64`.
`iv`	`number`	`16`	The Initialization Vector length in bytes. Minimum: `8`, Maximum: `32`.
`authTag`	`number`	`16`	The `authTag` length in bytes. Minimum: `4`, Maximum: `16`.
`aad`	`CoerceToUint8ArrayInput`	-	Custom Additional Authenticated Data. `aadLength` is then automatically resolved. If not provided, a random AAD is generated with a max length of `aadLength`.
`aadLength`	`number`	`32`	The auto generated AAD length in bytes. Minimum: `16`, Maximum: `128`.

`Cph.Stream.EncryptOptions`

Stream symmetric encryption options.

Properties

Property	Type	Description
`input`	`Readable`	The `Readable` Stream from where raw data to encrypt is read.
`output`	`Writable`	The `Writable` Stream where encrypted data is written.
`algorithm`	`Cph.CBCTypes`	One of the Cipher Block Chaining algorithm.

`Cph.Stream.DecryptOptions`

Stream symmetric decryption options.

Alias of Cph.Stream.EncryptOptions.

Properties

Property	Type	Description
`input`	`Readable`	The `Readable` Stream from where encrypted data is read.
`output`	`Writable`	The `Writable` Stream where decrypted data is written.
`algorithm`	`Cph.CBCTypes`	One of the Cipher Block Chaining algorithm.

`Cph.PrivateKey`

The RSA Private Key.

It could be:

a crypto.KeyLike
an object defining key and passphrase where key is a crypto.KeyLike

Examples

In-memory data buffer encryption/decryption

The simpliest way to encrypt/decrypt in-memory data buffers.

// encrypt
const data = "my top-secret data";
const password = "my-very-strong-password";

const encrypted = Cipher.Encrypt(data, password);

// decrypt
const decrypted = Cipher.Decrypt(encrypted, password);
console.log(decrypted); // Outputs: my top-secret data

In-memory data buffer hybrid encryption/decryption

Hybrid encryption offers an higher level of security since only the RSA Private Key owner will be able to decrypt the data.

Warning

Please, note that when using hybrid encryption/decryption algorithms:

an RSA keypair is required.
if a passphrase is set for the Private Key, please make sure to use one of the Cipher Block Chaining algorithm or chacha20-poly1305 algorithm:
- aes-128-cbc (type can be pkcs1 or pkcs8)
- aes-192-cbc (type can be pkcs1 or pkcs8)
- aes-256-cbc (type can be pkcs1 or pkcs8)
- chacha20-poly1305 (type can only be pkcs1)

Keypair

import { Cipher } from "@alessiofrittoli/crypto-cipher";

const keyPair = crypto.generateKeyPairSync("rsa", {
  modulusLength: 512 * 8, // 4096 bits
  publicKeyEncoding: { type: "spki", format: "pem" },
  privateKeyEncoding: { type: "pkcs1", format: "pem" },
});

// or you can optionally set a custom passphrase
const passphrase = "custompassphrase";

const keyPair = crypto.generateKeyPairSync("rsa", {
  modulusLength: 512 * 8, // 4096 bits
  publicKeyEncoding: { type: "spki", format: "pem" },
  privateKeyEncoding: {
    type: "pkcs1",
    format: "pem",
    passphrase,
    cipher: Cipher.ALGORITHM.CHACHA_20_POLY,
  },
});

import { Cipher } from "@alessiofrittoli/crypto-cipher";

// encrypt
const data = "my top-secret data";
const encrypted = Cipher.HybridEncrypt(data, keypair.publicKey);

// decrypt
const decrypted = Cipher.HybridDecrypt(encrypted, {
  key: keypair.privateKey,
  passphrase,
});

In-memory data stream encryption/decryption

The in-memory data stream comes pretty handy when, for example, we need to stream encrypted data within a Server Response or to decrypt stream data from a Server Response.

Streaming

// /api/stream-encrypt

import { Readable, Writable } from "stream";
import { Stream } from "@alessiofrittoli/stream-writer";

const routeHandler = () => {
  const password = "my-very-strong-password";
  const stream = new Stream();
  const headers = new Headers(stream.headers);

  const input = Readable.from([
    Buffer.from("Chunk n.1"),
    Buffer.from("Chunk n.2"),
    Buffer.from("Chunk n.3"),
    Buffer.from("Chunk n.4"),
  ]);

  // `Writable` Stream where encrypted data is written
  const output = new Writable({
    async write(chunk, encoding, callback) {
      await new Promise((resolve) => setTimeout(resolve, 2000));
      await stream.write(chunk);
      callback();
    },
    async final(callback) {
      await stream.close();
      callback();
    },
  });

  Cipher.stream.Encrypt(password, { input, output }).catch(async () => {
    await stream.close();
  });

  return (
    // encrypted stream
    new Response(stream.readable, { headers })
  );
};

Decrypting received stream

// /api/stream-decrypt

import { Transform, Writable } from "stream";
import { Cipher } from "@alessiofrittoli/crypto-cipher";
import { StreamReader } from "@alessiofrittoli/stream-reader";

const password = "my-very-strong-password";

const routeHandler = () =>
  fetch("/api/stream-encrypt").then((response) => {
    if (!response.body) {
      return new Respone(null, { status: 400 });
    }

    // web stream where decrypted data is written
    const stream = new Stream<Buffer, string>({
      transform(chunk, controller) {
        controller.enqueue(chunk.toString());
      },
    });
    const headers = new Headers(stream.headers);

    headers.set("Content-Type", "text/html");

    const reader = new StreamReader<Uint8Array, Buffer, false>(response.body, {
      inMemory: false,
      transform: Buffer.from,
    });

    const input = new Transform();

    reader.on("data", (chunk) => input.push(chunk));
    reader.on("close", () => input.end());

    reader.read();

    // `Writable` Stream where encrypted data is written
    const output = new Writable({
      async write(chunk: Buffer, encoding, callback) {
        await stream.write(chunk);
        callback();
      },
      final(callback) {
        stream.close();
        callback();
      },
    });

    Cipher.stream.Decrypt(password, { input, output }).catch(async (error) => {
      console.error(error);
      await stream.close();
    });

    return new Response(stream.readable, { headers });
  });

In-memory data stream with hybrid encryption/decryption

Hybrid encryption offers an higher level of security since only the RSA Private Key owner will be able to decrypt the data.

Warning

Please, note that when using hybrid encryption/decryption algorithms:

an RSA keypair is required.
if a passphrase is set for the Private Key, please make sure to use one of the Cipher Block Chaining algorithm or chacha20-poly1305 algorithm:
- aes-128-cbc (type can be pkcs1 or pkcs8)
- aes-192-cbc (type can be pkcs1 or pkcs8)
- aes-256-cbc (type can be pkcs1 or pkcs8)
- chacha20-poly1305 (type can only be pkcs1)

Keypair

import { Cipher } from "@alessiofrittoli/crypto-cipher";

const keyPair = crypto.generateKeyPairSync("rsa", {
  modulusLength: 512 * 8, // 4096 bits
  publicKeyEncoding: { type: "spki", format: "pem" },
  privateKeyEncoding: { type: "pkcs1", format: "pem" },
});

// or you can optionally set a custom passphrase
const passphrase = "custompassphrase";

const keyPair = crypto.generateKeyPairSync("rsa", {
  modulusLength: 512 * 8, // 4096 bits
  publicKeyEncoding: { type: "spki", format: "pem" },
  privateKeyEncoding: {
    type: "pkcs1",
    format: "pem",
    passphrase,
    cipher: Cipher.ALGORITHM.CHACHA_20_POLY,
  },
});

Encrypt

const data = "my top-secret data";
/** Store encrypted chunks for next example. */
const encryptedChunks: Buffer[] = [];

// Create a `Readable` Stream with raw data.
const input = new Readable({
  read() {
    this.push(data); // Push data to encrypt
    this.push(null); // Signal end of stream
  },
});

// Create a `Writable` Stream where encrypted data is written
const output = new Writable({
  write(chunk, encoding, callback) {
    // push written chunk to `encryptedChunks` for further usage.
    encryptedChunks.push(chunk);
    callback();
  },
});

await Cipher.stream.HybridEncrypt(keyPair.publicKey, { input, output });

Decrypt

/** Store decrypted chunks. */
const chunks: Buffer[] = [];
// Create a `Readable` Stream with encrypted data.
const input = Readable.from(encryptedChunks);

// Create a `Writable` Stream where decrypted data is written
const output = new Writable({
  write(chunk, encoding, callback) {
    chunks.push(chunk);
    callback();
  },
});

await Cipher.stream.HybridDecrypt(
  {
    key: keyPair.privateKey,
    passphrase, // optional passhrase (required if set while generating keypair).
  },
  { input, output }
);

console.log(Buffer.concat(chunks).toString()); // Outputs: 'my top-secret data'

File based data stream encryption/decryption

Nothig differs from the In-memory data stream encryption/decryption example, except for input and output streams which now comes directly from files reading/writing.

Encrypt a file

import fs from "fs";

const password = "my-very-strong-password";

// input where raw data to encrypt is read
const input = fs.createReadStream("my-very-large-top-secret-file.pdf");
// output where encrypted data is written
const output = fs.createWriteStream("my-very-large-top-secret-file.encrypted");
// encrypt
await Cipher.stream.Encrypt(password, { input, output });

Decrypt a file

import fs from "fs";

const password = "my-very-strong-password";

// input where encrypted data is read
const input = fs.createReadStream("my-very-large-top-secret-file.encrypted");
// output where decrypted data is written
const output = fs.createWriteStream(
  "my-very-large-top-secret-file-decrypted.pdf"
);
// decrypt
await Cipher.stream.Decrypt(password, { input, output });

File based data stream with hybrid encryption/decryption

Nothig differs from the In-memory data stream with hybrid encryption/decryption example, except for input and output streams which now comes directly from files reading/writing.

Warning

Please, note that when using hybrid encryption/decryption algorithms:

an RSA keypair is required.
if a passphrase is set for the Private Key, please make sure to use one of the Cipher Block Chaining algorithm or chacha20-poly1305 algorithm:
- aes-128-cbc (type can be pkcs1 or pkcs8)
- aes-192-cbc (type can be pkcs1 or pkcs8)
- aes-256-cbc (type can be pkcs1 or pkcs8)
- chacha20-poly1305 (type can only be pkcs1)

Keypair

import { Cipher } from "@alessiofrittoli/crypto-cipher";

const keyPair = crypto.generateKeyPairSync("rsa", {
  modulusLength: 512 * 8, // 4096 bits
  publicKeyEncoding: { type: "spki", format: "pem" },
  privateKeyEncoding: { type: "pkcs1", format: "pem" },
});

// or you can optionally set a custom passphrase
const passphrase = "custompassphrase";

const keyPair = crypto.generateKeyPairSync("rsa", {
  modulusLength: 512 * 8, // 4096 bits
  publicKeyEncoding: { type: "spki", format: "pem" },
  privateKeyEncoding: {
    type: "pkcs1",
    format: "pem",
    passphrase,
    cipher: Cipher.ALGORITHM.CHACHA_20_POLY,
  },
});

Encrypt a file

import fs from "fs";

// input where raw data to encrypt is read
const input = fs.createReadStream("my-very-large-top-secret-file.pdf");
// output where encrypted data is written
const output = fs.createWriteStream("my-very-large-top-secret-file.encrypted");
// encrypt
await Cipher.stream.HybridEncrypt(keyPair.publicKey, { input, output });

Decrypt a file

import fs from "fs";

// input where encrypted data is read
const input = fs.createReadStream("my-very-large-top-secret-file.encrypted");
// output where decrypted data is written
const output = fs.createWriteStream(
  "my-very-large-top-secret-file-decrypted.pdf"
);
// decrypt
const { decrypt } = await Cipher.stream.HybridDecrypt(
  {
    key: keyPair.privateKey,
    passphrase, // optional passhrase (required if set while generating keypair).
  },
  { input, output }
);

Development

Install depenendencies

npm install

or using pnpm

pnpm i

Build the source code

Run the following command to test and build code for distribution.

pnpm build

ESLint

warnings / errors check.

pnpm lint

Jest

Run all the defined test suites by running the following:

# Run tests and watch file changes.
pnpm test:watch

# Run tests in a CI environment.
pnpm test:ci

See package.json file scripts for more info.

Run tests with coverage.

An HTTP server is then started to serve coverage files from ./coverage folder.

⚠️ You may see a blank page the first time you run this command. Simply refresh the browser to see the updates.

test:coverage:serve

Contributing

Contributions are truly welcome!

Please refer to the Contributing Doc for more information on how to start contributing to this project.

Help keep this project up to date with GitHub Sponsor.

Security

If you believe you have found a security vulnerability, we encourage you to responsibly disclose this and NOT open a public issue. We will investigate all legitimate reports. Email security@alessiofrittoli.it to disclose any security vulnerabilities.

Made with ☕

Alessio Frittoli

https://alessiofrittoli.it | info@alessiofrittoli.it

Name		Name	Last commit message	Last commit date
Latest commit History 25 Commits
.github		.github
.vscode		.vscode
__tests__		__tests__
scripts		scripts
src		src
.editorconfig		.editorconfig
.gitignore		.gitignore
.markdownlint.json		.markdownlint.json
.npmignore		.npmignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
README.md		README.md
alessiofrittoli-env.d.ts		alessiofrittoli-env.d.ts
eslint.config.mjs		eslint.config.mjs
jest.config.ts		jest.config.ts
license.md		license.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts

Uh oh!

License

alessiofrittoli/crypto-cipher

Folders and files

Latest commit

History

Repository files navigation

Crypto Cipher 🔐

Node.js Cipher cryptograph utility library

Table of Contents

Getting started

Key features

Security Considerations

Readable and Modular

What's Changed

Migration guide

Migrating from v2.x.x to v3.0.0

API Reference

Constants

Cipher.SALT_LENGTH

Cipher.IV_LENGTH

Cipher.AUTH_TAG_LENGTH

Cipher.AAD_LENGTH

Cipher.DEFAULT_ALGORITHM

Cipher.ALGORITHM

Cipher.ALGORITHMS

Methods

Cipher.Encrypt()

Cipher.Decrypt()

Cipher.HybridEncrypt()

Cipher.HybridDecrypt()

Cipher.stream.Encrypt()

Cipher.stream.Decrypt()

Cipher.stream.HybridEncrypt()

Cipher.stream.HybridDecrypt()

Types

CoerceToUint8ArrayInput

Cph.CBCTypes

Cph.AesAlgorithm

Cph.Options<T>

Cph.Stream.EncryptOptions

Cph.Stream.DecryptOptions

Cph.PrivateKey

Examples

In-memory data buffer encryption/decryption

In-memory data buffer hybrid encryption/decryption

Keypair

In-memory data stream encryption/decryption

Streaming

Decrypting received stream

In-memory data stream with hybrid encryption/decryption

Keypair

Encrypt

Decrypt

File based data stream encryption/decryption

Encrypt a file

Decrypt a file

File based data stream with hybrid encryption/decryption

Keypair

Encrypt a file

Decrypt a file

Development

Install depenendencies

Build the source code

ESLint

Jest

Contributing

Security

Made with ☕

About

Topics

Resources

License

Code of conduct

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 10

`Cipher.SALT_LENGTH`

`Cipher.IV_LENGTH`

`Cipher.AUTH_TAG_LENGTH`

`Cipher.AAD_LENGTH`

`Cipher.DEFAULT_ALGORITHM`

`Cipher.ALGORITHM`

`Cipher.ALGORITHMS`

`Cipher.Encrypt()`

`Cipher.Decrypt()`

`Cipher.HybridEncrypt()`

`Cipher.HybridDecrypt()`

`Cipher.stream.Encrypt()`

`Cipher.stream.Decrypt()`

`Cipher.stream.HybridEncrypt()`

`Cipher.stream.HybridDecrypt()`

`CoerceToUint8ArrayInput`

`Cph.CBCTypes`

`Cph.AesAlgorithm`

`Cph.Options<T>`

`Cph.Stream.EncryptOptions`

`Cph.Stream.DecryptOptions`

`Cph.PrivateKey`