Cipher

The Cipher module provides implementations of symmetric cipher algorithms. It supports standard Block Ciphers (AES) and Stream Ciphers (ChaCha20).

Table of Contents

• Theory
• Class: Cipher
• Class: Decipher
• Module Methods
• Real-World Examples

Theory

Symmetric ciphers use the same key for encryption and decryption.

• Block Ciphers (e.g., AES) operate on fixed-size blocks of data (16 bytes).
• Modes of Operation determine how to encrypt data larger than a single block.
  • GCM (Galois/Counter Mode): Provides both encryption and integrity (AEAD). Recommended.
  • CBC (Cipher Block Chaining): Older standard. Malleable and requires padding.

AEAD (Authenticated Encryption with Associated Data) ensures that the data cannot be modified by an attacker. It produces an Authentication Tag. If the tag doesn't match upon decryption, the operation fails.

Class: Cipher

Instances of the Cipher class are used to encrypt data.

cipher.update(data[, inputEncoding][, outputEncoding])

Encrypts data.

Parameters:

Returns: Buffer | string

cipher.final([outputEncoding])

Returns any remaining encrypted data.

cipher.getAuthTag()

For AEAD modes (GCM, CCM, Poly1305), returns the authentication tag. Must be called after final().

Returns: Buffer

cipher.setAAD(buffer[, options])

Sets "Additional Authenticated Data" (AAD). This is data that is not encrypted but is authenticated (integrity protected).

Class: Decipher

Instances of the Decipher class are used to decrypt data.

decipher.update(data[, inputEncoding][, outputEncoding])

decipher.final([outputEncoding])

decipher.setAuthTag(buffer)

Sets the tag to verify. Must be called before final().

decipher.setAAD(buffer)

Sets AAD to verify. Must be called before final().

Module Methods

createCipheriv(algorithm, key, iv[, options])

Creates and returns a Cipher object.

Parameters:

Returns: Cipher

createDecipheriv(algorithm, key, iv[, options])

Creates and returns a Decipher object.

Returns: Decipher

Real-World Examples

Authenticated Encryption (GCM)

Complete encryption flow with integrity check.

import { createCipheriv, randomBytes } from 'react-native-quick-crypto';

const key = randomBytes(32);

function encrypt(text: string) {
    const iv = randomBytes(12);
    const cipher = createCipheriv('aes-256-gcm', key, iv);
    
    let enc = cipher.update(text, 'utf8', 'hex');
    enc += cipher.final('hex');
    
    const tag = cipher.getAuthTag();
    
    return { 
        data: enc, 
        iv: iv.toString('hex'), 
        tag: tag.toString('hex') 
    };
}

File Encryption (Scanning)

Encrypting a file using streams with AES-CTR (counter mode).

import { createCipheriv } from 'react-native-quick-crypto';
const fs = require('fs'); // Mock

const key = randomBytes(32);
const iv = randomBytes(16);

const cipher = createCipheriv('aes-256-ctr', key, iv);
const input = fs.createReadStream('input.txt');
const output = fs.createWriteStream('output.enc');

input.pipe(cipher).pipe(output);