https://github.com/alessiofrittoli/crypto-cipher

Node.js Cipher cryptograph utility library
https://github.com/alessiofrittoli/crypto-cipher
aes-encryption cipher encryption encryption-decryption stream-encryption
Last synced: 6 months ago
JSON representation
Node.js Cipher cryptograph utility library
Host: GitHub
URL: https://github.com/alessiofrittoli/crypto-cipher
Owner: alessiofrittoli
License: mit
Created: 2025-01-12T22:25:12.000Z (over 1 year ago)
Default Branch: master
Last Pushed: 2025-03-22T15:52:56.000Z (over 1 year ago)
Last Synced: 2025-03-22T15:55:13.674Z (over 1 year ago)
Topics: aes-encryption, cipher, encryption, encryption-decryption, stream-encryption
Language: TypeScript
Homepage: https://npmjs.com/package/@alessiofrittoli/crypto-cipher
Size: 167 KB
Stars: 0
Watchers: 1
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: license.md
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project

README

          # Crypto Cipher 🔐

[![NPM Latest Version][version-badge]][npm-url] [![Coverage Status][coverage-badge]][coverage-url] [![Socket Status][socket-badge]][socket-url] [![NPM Monthly Downloads][downloads-badge]][npm-url] [![Dependencies][deps-badge]][deps-url]

[![GitHub Sponsor][sponsor-badge]][sponsor-url]

[version-badge]: https://img.shields.io/npm/v/%40alessiofrittoli%2Fcrypto-cipher

[npm-url]: https://npmjs.org/package/%40alessiofrittoli%2Fcrypto-cipher

[coverage-badge]: https://coveralls.io/repos/github/alessiofrittoli/crypto-cipher/badge.svg

[coverage-url]: https://coveralls.io/github/alessiofrittoli/crypto-cipher

[socket-badge]: https://socket.dev/api/badge/npm/package/@alessiofrittoli/crypto-cipher

[socket-url]: https://socket.dev/npm/package/@alessiofrittoli/crypto-cipher/overview

[downloads-badge]: https://img.shields.io/npm/dm/%40alessiofrittoli%2Fcrypto-cipher.svg

[deps-badge]: https://img.shields.io/librariesio/release/npm/%40alessiofrittoli%2Fcrypto-cipher

[deps-url]: https://libraries.io/npm/%40alessiofrittoli%2Fcrypto-cipher

[sponsor-badge]: https://img.shields.io/static/v1?label=Fund%20this%20package&message=%E2%9D%A4&logo=GitHub&color=%23DB61A2

[sponsor-url]: https://github.com/sponsors/alessiofrittoli

## Node.js Cipher cryptograph utility library

### Table of Contents

- [Getting started](#getting-started)

- [Key features](#key-features)

- [API Reference](#api-reference)

  - [Importing the library](#importing-the-library)

  - [Constants](#constants)

  - [Methods](#methods)

    - [`Cipher.encrypt()`](#cipherencrypt)

    - [`Cipher.decrypt()`](#cipherdecrypt)

    - [`Cipher.streamEncrypt()`](#cipherstreamencrypt)

    - [`Cipher.streamDecrypt()`](#cipherstreamencrypt)

    - [`Cipher.hybridEncrypt()`](#cipherhybridencrypt)

    - [`Cipher.hybridDecrypt()`](#cipherhybriddecrypt)

  - [Types](#types)

- [Examples](#examples)

  - [In-memory data buffer encryption/decryption](#in-memory-data-buffer-encryptiondecryption)

  - [In-memory data stream encryption/decryption](#in-memory-data-stream-encryptiondecryption)

  - [In-memory data stream with hybrid encryption/decryption](#in-memory-data-stream-with-hybrid-encryptiondecryption)

  - [File based data stream encryption/decryption](#file-based-data-stream-encryptiondecryption)

  - [File based data stream with hybrid encryption/decryption](#file-based-data-stream-with-hybrid-encryptiondecryption)

- [Development](#development)

  - [ESLint](#eslint)

  - [Jest](#jest)

- [Contributing](#contributing)

- [Security](#security)

- [Credits](#made-with-)

---

### 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](https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf) 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`](https://npmjs.com/search?q=%40alessiofrittoli%2Fcrypto) utility libraries and can be installed by running the following command:

```bash

npm i @alessiofrittoli/crypto-cipher

```

or using `pnpm`

```bash

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), with seamless handling of key/IV extraction.

- Hybrid encryption methods for combining symmetric and asymmetric cryptography.

#### Options Management

- A solid options resolver mechanism ensures consistent handling of defaults and constraints.

#### Security Considerations

- Random `salt` and `IV` generation.

- 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.

---

### 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.ALGORITHMS`

Supported AES algorithms:

Properties

- `aes-128-gcm`

- `aes-192-gcm`

- `aes-256-gcm`

- `aes-128-ccm`

- `aes-192-ccm`

- `aes-256-ccm`

- `aes-128-ocb`

- `aes-192-ocb`

- `aes-256-ocb`

- `aes-128-cbc`

- `aes-192-cbc`

- `aes-256-cbc`

- `chacha20-poly1305`

---

#### Methods

##### `Cipher.encrypt()`

Encrypts an in-memory data buffer.

⚠️ This is not suitable for large data.

Use [`Cipher.streamEncrypt()`](#cipherstreamencrypt) or [`Cipher.hybridEncrypt()`](#cipherhybridencrypt) 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`](#coercetouint8arrayinput) for more informations about supported input data types.

- See [`Cph.Options`](#cphoptionst) for more informations about additional encryption options.

- See [In-memory data buffer encryption/decryption](#in-memory-data-buffer-encryptiondecryption) examples.

---

##### `Cipher.decrypt()`

Decrypts an in-memory data buffer.

⚠️ This is not suitable for large data.

Use [`Cipher.streamDecrypt()`](#cipherstreamdecrypt) or [`Cipher.hybridDecrypt()`](#cipherhybriddecrypt) 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`](#coercetouint8arrayinput) for more informations about supported input data types.

- See [`Cph.Options`](#cphoptionst) for more informations about additional decryption options.

- See [In-memory data buffer encryption/decryption](#in-memory-data-buffer-encryptiondecryption) examples.

---

##### `Cipher.streamEncrypt()`

Encrypts a `Readable` stream to a `Writable` stream.

Parameters

| Name      | Type                              | Description                           |

|-----------|-----------------------------------|---------------------------------------|

| `secret`  | `CoerceToUint8ArrayInput`         | Secret key for encryption.            |

| `options` | `Cph.Stream.Symmetric.EncryptOptions` | Stream encryption options.        |

---

Returns

Type: `Cph.Stream.Symmetric.EncryptReturnType`

- An object containing:

  - a new instance of `crypto.Cipher` allowing you to add listeners to the `cipher` encryption process.

  - the actual `encrypt` callback that must be called and awaited in order to start the encryption process.

---

- See [`CoerceToUint8ArrayInput`](#coercetouint8arrayinput) for more informations about supported input data types.

- See [`Cph.Stream.Symmetric.EncryptOptions`](#cphstreamsymmetricencryptoptions) for more informations about encryption options.

- See [In-memory data stream encryption/decryption](#in-memory-data-stream-encryptiondecryption) examples.

- See [File based data stream encryption/decryption](#file-based-data-stream-encryptiondecryption) examples.

---

##### `Cipher.streamDecrypt()`

Decrypts a `Readable` stream to a `Writable` stream.

Parameters

| Name      | Type                              | Description                           |

|-----------|-----------------------------------|---------------------------------------|

| `secret`  | `CoerceToUint8ArrayInput`         | Secret key for decryption.            |

| `options` | `Cph.Stream.Symmetric.DecryptOptions` | Stream decryption options.            |

---

Returns

Type: `Promise`

- A new Promise that resolves when Key IV extraction completes returning an object containing:

  - a new instance of `crypto.Decipher` allowing you to add listeners to the `decipher` decryption process.

  - the actual `decrypt` callback that must be called and awaited in order to start the decryption process.

---

- See [`CoerceToUint8ArrayInput`](#coercetouint8arrayinput) for more informations about supported input data types.

- See [`Cph.Stream.Symmetric.DecryptOptions`](#cphstreamsymmetricdecryptoptions) for more informations about decryption options.

- See [In-memory data stream encryption/decryption](#in-memory-data-stream-encryptiondecryption) examples.

- See [File based data stream encryption/decryption](#file-based-data-stream-encryptiondecryption) examples.

---

##### `Cipher.hybridEncrypt()`

Encrypts a stream using hybrid encryption (symmetric + RSA).

Parameters

| Name        | Type                              | Description                           |

|-------------|-----------------------------------|---------------------------------------|

| `secret`    | `CoerceToUint8ArrayInput`         | Symmetric secret key.                 |

| `publicKey` | `crypto.RsaPublicKey \| crypto.KeyLike` | RSA public key used to encrypt the generated symmetric key. |

| `options`   | `Cph.Stream.Hybrid.EncryptOptions` | Stream encryption options.        |

---

Returns

Type: `Cph.Stream.Hybrid.EncryptReturnType`

- An object containing:

  - a new instance of `cipher` allowing you to add listeners to the `cipher` encryption process.

  - the actual `encrypt` callback that must be called and awaited to start the encryption process.

---

- See [`CoerceToUint8ArrayInput`](#coercetouint8arrayinput) for more informations about supported input data types.

- See [`Cph.Stream.Hybrid.EncryptOptions`](#cphstreamhybridencryptoptions) for more informations about encryption options.

- See [In-memory data stream with hybrid encryption/decryption](#in-memory-data-stream-with-hybrid-encryptiondecryption) examples.

- See [File based data stream with hybrid encryption/decryption](#file-based-data-stream-with-hybrid-encryptiondecryption) examples.

---

##### `Cipher.hybridDecrypt()`

Decrypts a stream using hybrid decryption (symmetric + RSA).

Parameters

| Name         | Type                              | Description                           |

|--------------|-----------------------------------|---------------------------------------|

| `privateKey` | `crypto.RsaPrivateKey \| crypto.KeyLike` | RSA private key for used to decrpyt the encrypted symmetric key. |

| `options`    | `Cph.Stream.Hybrid.DecryptOptions` | Stream decryption options.           |

---

Returns

Type: `Promise`

- A new Promise that resolves when Key IV extraction completes returning an object containing:

  - a new instance of `crypto.Decipher` allowing you to add listeners to the `decipher` decryption process.

  - the actual `decrypt` callback that must be called and awaited in order to start the decryption process.

---

- See [`Cph.Stream.Hybrid.DecryptOptions`](#cphstreamhybriddecryptoptions) for more informations about decryption options.

- See [In-memory data stream with hybrid encryption/decryption](#in-memory-data-stream-with-hybrid-encryptiondecryption) examples.

- See [File based data stream with hybrid encryption/decryption](#file-based-data-stream-with-hybrid-encryptiondecryption) examples.

---

#### Types

##### `CoerceToUint8ArrayInput`

This module supports different input data types and it uses the [`coerceToUint8Array`](https://npmjs.com/package/@alessiofrittoli/crypto-buffer#coercetouint8array) utility function from [`@alessiofrittoli/crypto-buffer`](https://npmjs.com/package/@alessiofrittoli/crypto-buffer) to convert it to a `Uint8Array`.

- See [`coerceToUint8Array`](https://npmjs.com/package/@alessiofrittoli/crypto-buffer#coercetouint8array) for more informations about the supported input types.

---

##### `Cph.CBCTypes`

Cipher CBC algorithm types.

---

##### `Cph.AesAlgorithm`

Supported AES algorithm types.

---

##### `Cph.Options`

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.Symmetric.EncryptOptions`

Stream symmetric encryption options.

- Extends [`Cph.Options`](#cphoptionst).

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. |

---

##### `Cph.Stream.Symmetric.EncryptReturnType`

Returnign object from `Cipher.streamEncrypt()` method.

Properties

| Property | Type     | Description |

|----------|----------|-------------|

| `cipher`  | `crypto.Cipher` | The `crypto.Cipher` instance. |

| `encrypt` | `() => Promise` | The actual `encrypt` callback that must be called and awaited in order to start the encryption process. |

---

##### `Cph.Stream.Symmetric.DecryptOptions`

Stream symmetric decryption options.

- Extends [`Cph.Stream.Symmetric.EncryptOptions`](#cphstreamsymmetricencryptoptions).

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. |

---

##### `Cph.Stream.Symmetric.DecryptReturnType`

Returnign object from awaited `Cipher.streamDecrypt()` method.

Properties

| Property | Type     | Description |

|----------|----------|-------------|

| `decipher` | `crypto.Decipher` | The `crypto.Decipher` instance. |

| `decrypt` | `() => Promise` | The actual `decrypt` callback that must be called and awaited in order to start the decryption process. |

---

##### `Cph.Stream.Hybrid.EncryptOptions`

Stream hybrid encryption options.

- Alias for [`Cph.Stream.Symmetric.EncryptOptions`](#cphstreamsymmetricencryptoptions)

---

##### `Cph.Stream.Hybrid.EncryptReturnType`

Returnign object from `Cipher.hybridEncrypt()` method.

- Alias for [`Cph.Stream.Symmetric.EncryptReturnType`](#cphstreamsymmetricencryptreturntype)

---

##### `Cph.Stream.Hybrid.DecryptOptions`

Stream hybrid decryption options.

- Extends [`Cph.Stream.Symmetric.DecryptOptions`](#cphstreamsymmetricdecryptoptions).

Properties

| Property       | Type     | Description |

|----------------|----------|-------------|

| `rsaKeyLength` | `number` | The RSA key length in bytes used while encrypting data. This is used to properly extract the encrypted Cipher Key and Initialization Vector from the encrypted data. |

---

##### `Cph.Stream.Hybrid.DecryptReturnType`

Returnign object from awaited `Cipher.hybridDecrypt()` method.

- Alias for [`Cph.Stream.Symmetric.DecryptReturnType`](#cphstreamsymmetricdecryptreturntype)

---

### Examples

#### Importing the library

```ts

import { Cipher } from '@alessiofrittoli/crypto-cipher'

import type { Cph as CipherTypes } from '@alessiofrittoli/crypto-cipher/types'

```

#### In-memory data buffer encryption/decryption

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

```ts

// 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 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

```ts

// /api/stream-encrypt

import { Readable, Writable } from 'stream'

const routeHandler = () => {

  const data      = 'my top-secret data'

  const password  = 'my-very-strong-password'

  const stream    = new TransformStream()

  const writer    = stream.writable.getWriter()

  

  // Create a `Readable` Stream with raw data.

  const input = new Readable( {

    read()

    {

      this.push( data )

      this.push( null ) // Signal end of stream

    },

  } )

      

  // `Writable` Stream where encrypted data is written

  const output = new Writable( {

    write( chunk, encoding, callback )

    {

      writer.write( chunk )

      callback()

    },

    final( callback )

    {

      writer.close()

      callback()

    }

  } )

  

  Cipher.streamEncrypt( password, { input, output } )

    .encrypt()

  

  return (

    // encrypted stream

    new Response( stream.readable )

  )

}

```

##### Decrypting received stream

```ts

// /api/stream-decrypt

import { Transform, Writable } from 'stream'

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

        )

      }

      const stream  = new TransformStream()

      const writer  = stream.writable.getWriter()

      const reader  = new StreamReader( response.body )

      const input   = new Transform()

      

      reader.read()

      

      reader.on( 'read', chunk => {

        input.push( chunk )

      } )

      reader.on( 'close', () => {

        input.push( null )

      } )

      const output = new Writable( {

        write( chunk, encoding, callback )

        {

          writer.write( chunk )

          callback()

        },

        final( callback ) {

          writer.close()

          callback()

        },

      } )

      

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

      decrypt()

      

      return (

        // decrypted stream

        new Response( stream.readable )

      )

      

    } )

)

```

---

#### In-memory data stream with hybrid encryption/decryption

Hybrid encryption offers an higher level of security by encrypting the generated symmetric key with asymmetric RSA keys.

##### Keypair

```ts

const password  = 'my-very-strong-password'

/** RSA modulus length is required for proper key extraction during decryption process. */

const rsaKeyLength = 512 // bytes

const keyPair = crypto.generateKeyPairSync( 'rsa', {

  modulusLength       : rsaKeyLength * 8, // 4096 bits

  publicKeyEncoding   : { type: 'spki', format: 'pem' },

  privateKeyEncoding  : { type: 'pkcs1', format: 'pem' },

} )

// or you can optionally set a custom passphrase

const keyPair = crypto.generateKeyPairSync( 'rsa', {

  modulusLength       : rsaKeyLength * 8, // 4096 bits

  publicKeyEncoding   : { type: 'spki', format: 'pem' },

  privateKeyEncoding  : { type: 'pkcs1', format: 'pem', passphrase: password, cipher: 'aes-256-cbc' },

} )

```

##### Encrypt

```ts

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

  }

} )

const { encrypt } = Cipher.hybridEncrypt( password, {

  key       : keyPair.publicKey,

  padding   : crypto.constants.RSA_PKCS1_OAEP_PADDING,

  oaepHash  : 'SHA-256',

}, { input, output } )

await encrypt()

```

---

##### Decrypt

```ts

/** Store decrypted chunks. */

const chunks: Buffer[] = []

// Create a `Readable` Stream with encrypted data.

const input = new Readable( {

  read()

  {

    this.push( Buffer.concat( encryptedChunks ) ) // Push data to decrypt

    this.push( null ) // Signal end of stream

  },

} )

// Create a `Writable` Stream where decrypted data is written

const output = new Writable( {

  write( chunk, encoding, callback )

  {

    chunks.push( chunk )

    callback()

  },

} )

const { decrypt } = await Cipher.hybridDecrypt(

  {

    key       : keyPair.privateKey,

    passphrase: password, // optional passhrase (required if set while generating keypair).

    padding   : crypto.constants.RSA_PKCS1_OAEP_PADDING,

    oaepHash  : 'SHA-256',

  }, { input, output, rsaKeyLength }

)

await decrypt()

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](#in-memory-data-stream-encryptiondecryption) example, except for `input` and `output` streams which now comes directly from files reading/writing.

##### Encrypt a file

```ts

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.streamEncrypt( password, { input, output } )

  .encrypt()

```

---

##### Decrypt a file

```ts

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

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

await decrypt()

```

---

#### File based data stream with hybrid encryption/decryption

Nothig differs from the [In-memory data stream with hybrid encryption/decryption](#in-memory-data-stream-with-hybrid-encryptiondecryption) example, except for `input` and `output` streams which now comes directly from files reading/writing.

##### Keypair

```ts

const password  = 'my-very-strong-password'

/** RSA modulus length is required for proper key extraction during decryption process. */

const rsaKeyLength = 512 // bytes

const keyPair = crypto.generateKeyPairSync( 'rsa', {

  modulusLength       : rsaKeyLength * 8, // 4096 bits

  publicKeyEncoding   : { type: 'spki', format: 'pem' },

  privateKeyEncoding  : { type: 'pkcs1', format: 'pem' },

} )

// or you can optionally set a custom passphrase

const keyPair = crypto.generateKeyPairSync( 'rsa', {

  modulusLength       : rsaKeyLength * 8, // 4096 bits

  publicKeyEncoding   : { type: 'spki', format: 'pem' },

  privateKeyEncoding  : { type: 'pkcs1', format: 'pem', passphrase: password, cipher: 'aes-256-cbc' },

} )

```

##### Encrypt a file

```ts

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

const { encrypt } = Cipher.hybridEncrypt( password, {

  key       : keyPair.publicKey,

  padding   : crypto.constants.RSA_PKCS1_OAEP_PADDING,

  oaepHash  : 'SHA-256',

}, { input, output } )

await encrypt()

```

---

##### Decrypt a file

```ts

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

const { decrypt } = await Cipher.hybridDecrypt(

  {

    key       : keyPair.privateKey,

    passphrase: password, // optional passhrase (required if set while generating keypair).

    padding   : crypto.constants.RSA_PKCS1_OAEP_PADDING,

    oaepHash  : 'SHA-256',

  }, { input, output, rsaKeyLength }

)

```

---

### Development

#### Install depenendencies

```bash

npm install

```

or using `pnpm`

```bash

pnpm i

```

#### Build the source code

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

```bash

pnpm build

```

#### [ESLint](https://www.npmjs.com/package/eslint)

warnings / errors check.

```bash

pnpm lint

```

#### [Jest](https://npmjs.com/package/jest)

Run all the defined test suites by running the following:

```bash

# Run tests and watch file changes.

pnpm test:watch

# Run tests in a CI environment.

pnpm test:ci

```

- See [`package.json`](./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.

```bash

test:coverage:serve

```

---

### Contributing

Contributions are truly welcome!

Please refer to the [Contributing Doc](./CONTRIBUTING.md) for more information on how to start contributing to this project.

Help keep this project up to date with [GitHub Sponsor][sponsor-url].

[![GitHub Sponsor][sponsor-badge]][sponsor-url]

---

### 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
ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/alessiofrittoli/crypto-cipher

Awesome Lists containing this project

README
