CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-node-forge

JavaScript implementations of network transports, cryptography, ciphers, PKI, message digests, and various utilities.

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

symmetric-encryption.mddocs/

Symmetric Encryption

Block cipher implementations including AES, DES, and RC2 with support for various modes (CBC, CFB, OFB, CTR, GCM). Node-forge provides a unified cipher interface for all symmetric encryption algorithms with consistent API patterns.

Capabilities

Cipher Creation

Create encryption and decryption ciphers for symmetric algorithms.

/**
 * Create a cipher for encryption
 * @param algorithm - Algorithm name (e.g., 'AES-CBC', 'DES-EDE3-CBC', 'RC2-CBC')
 * @param key - Encryption key as binary string or ByteStringBuffer
 * @returns BlockCipher instance for encryption
 */
forge.cipher.createCipher(algorithm: string, key: string | ByteStringBuffer): BlockCipher;

/**
 * Create a decipher for decryption
 * @param algorithm - Algorithm name (e.g., 'AES-CBC', 'DES-EDE3-CBC', 'RC2-CBC')
 * @param key - Decryption key as binary string or ByteStringBuffer
 * @returns BlockCipher instance for decryption
 */
forge.cipher.createDecipher(algorithm: string, key: string | ByteStringBuffer): BlockCipher;

interface BlockCipher {
  /** Start the cipher operation with optional parameters */
  start(options?: CipherOptions): void;
  /** Update cipher with input data */
  update(input?: ByteStringBuffer): void;
  /** Complete the cipher operation */
  finish(pad?: (input: ByteStringBuffer) => void): boolean;
  /** Output buffer containing processed data */
  output: ByteStringBuffer;
  /** Block size for the cipher algorithm */
  blockSize: number;
}

interface CipherOptions {
  /** Initialization vector for modes that require it */
  iv?: string | ByteStringBuffer;
  /** Additional authenticated data for GCM mode */
  additionalData?: string;
  /** Authentication tag length for GCM mode (default: 128 bits) */
  tagLength?: number;
  /** Authentication tag for GCM decryption */
  tag?: string | ByteStringBuffer;
  /** Output buffer (optional) */
  output?: ByteStringBuffer;
}

Usage Examples:

const forge = require('node-forge');

// AES-CBC Encryption
const key = forge.random.getBytesSync(32); // 256-bit key
const iv = forge.random.getBytesSync(16);  // 128-bit IV

const cipher = forge.cipher.createCipher('AES-CBC', key);
cipher.start({iv: iv});
cipher.update(forge.util.createBuffer('secret message'));
cipher.finish();
const encrypted = cipher.output.getBytes();

// AES-CBC Decryption
const decipher = forge.cipher.createDecipher('AES-CBC', key);
decipher.start({iv: iv});
decipher.update(forge.util.createBuffer(encrypted));
decipher.finish();
const decrypted = decipher.output.toString();

// AES-GCM with authentication
const gcmCipher = forge.cipher.createCipher('AES-GCM', key);
gcmCipher.start({
  iv: iv,
  additionalData: 'authenticated but not encrypted data',
  tagLength: 128
});
gcmCipher.update(forge.util.createBuffer('confidential message'));
gcmCipher.finish();
const encryptedGcm = gcmCipher.output.getBytes();
const authTag = gcmCipher.mode.tag.getBytes();

Supported Algorithms

Node-forge supports multiple symmetric cipher algorithms with various modes.

// AES (Advanced Encryption Standard)
'AES-CBC'     // AES with CBC mode
'AES-CFB'     // AES with CFB mode  
'AES-OFB'     // AES with OFB mode
'AES-CTR'     // AES with CTR mode
'AES-GCM'     // AES with GCM mode (authenticated encryption)

// 3DES (Triple DES)
'DES-EDE3-CBC' // 3DES with CBC mode
'DES-EDE3-CFB' // 3DES with CFB mode
'DES-EDE3-OFB' // 3DES with OFB mode

// DES (Data Encryption Standard)
'DES-CBC'     // DES with CBC mode
'DES-CFB'     // DES with CFB mode
'DES-OFB'     // DES with OFB mode

// RC2
'RC2-CBC'     // RC2 with CBC mode
'RC2-CFB'     // RC2 with CFB mode
'RC2-OFB'     // RC2 with OFB mode

AES-Specific Functions

Direct AES cipher creation with legacy API support.

/**
 * Create AES encryption cipher (legacy API)
 * @param key - AES key (128, 192, or 256 bits)
 * @param mode - Cipher mode (default: 'CBC')
 * @returns AES encryption cipher
 * @deprecated Use forge.cipher.createCipher('AES-<mode>', key) instead
 */
forge.aes.createEncryptionCipher(key: string | ByteStringBuffer, mode?: string): BlockCipher;

/**
 * Create AES decryption cipher (legacy API)
 * @param key - AES key (128, 192, or 256 bits)
 * @param mode - Cipher mode (default: 'CBC')
 * @returns AES decryption cipher
 * @deprecated Use forge.cipher.createDecipher('AES-<mode>', key) instead
 */
forge.aes.createDecryptionCipher(key: string | ByteStringBuffer, mode?: string): BlockCipher;

Cipher Mode Operations

Different cipher modes provide various security and performance characteristics.

CBC (Cipher Block Chaining):

  • Requires IV (Initialization Vector)
  • Sequential processing
  • Good for data at rest
  • Requires padding for partial blocks

CFB (Cipher Feedback):

  • Requires IV
  • Stream cipher mode
  • No padding required
  • Good for real-time data

OFB (Output Feedback):

  • Requires IV
  • Stream cipher mode
  • No padding required
  • Synchronous stream cipher

CTR (Counter Mode):

  • Requires IV/counter
  • Stream cipher mode
  • Parallelizable
  • No padding required

GCM (Galois/Counter Mode):

  • Authenticated encryption
  • Requires IV
  • Provides authenticity and confidentiality
  • Additional authenticated data support

Usage Examples:

// CBC Mode with padding
const cbcCipher = forge.cipher.createCipher('AES-CBC', key);
cbcCipher.start({iv: iv});
cbcCipher.update(forge.util.createBuffer('data that needs padding'));
cbcCipher.finish(); // Automatic PKCS#7 padding

// CTR Mode (no padding needed)
const ctrCipher = forge.cipher.createCipher('AES-CTR', key);
ctrCipher.start({iv: iv});
ctrCipher.update(forge.util.createBuffer('any length data'));
ctrCipher.finish();

// GCM Mode with authentication
const gcmCipher = forge.cipher.createCipher('AES-GCM', key);
gcmCipher.start({
  iv: forge.random.getBytesSync(12), // 96-bit IV recommended for GCM
  additionalData: 'metadata'
});
gcmCipher.update(forge.util.createBuffer('authenticated and encrypted'));
gcmCipher.finish();
const tag = gcmCipher.mode.tag.getBytes(); // Store tag for verification

Key Length Requirements

Different algorithms require specific key lengths.

// AES Key Lengths
AES_128_KEY_LENGTH = 16;  // 128-bit key (16 bytes)
AES_192_KEY_LENGTH = 24;  // 192-bit key (24 bytes)  
AES_256_KEY_LENGTH = 32;  // 256-bit key (32 bytes)

// DES Key Lengths
DES_KEY_LENGTH = 8;       // 64-bit key (8 bytes, 56 effective)
DES_EDE3_KEY_LENGTH = 24; // 192-bit key (24 bytes) for 3DES

// RC2 Key Lengths
RC2_KEY_LENGTH_MIN = 1;   // Minimum 8-bit key
RC2_KEY_LENGTH_MAX = 128; // Maximum 1024-bit key

Key Generation Examples:

// Generate secure random keys
const aes128Key = forge.random.getBytesSync(16);  // 128-bit AES key
const aes256Key = forge.random.getBytesSync(32);  // 256-bit AES key
const desKey = forge.random.getBytesSync(8);      // DES key
const des3Key = forge.random.getBytesSync(24);    // 3DES key

// Derive key from password using PBKDF2
const salt = forge.random.getBytesSync(16);
const derivedKey = forge.pkcs5.pbkdf2('password', salt, 100000, 32);

Algorithm Registry

Register custom cipher algorithms with the cipher framework.

/**
 * Register a cipher algorithm
 * @param name - Algorithm name
 * @param algorithm - Algorithm implementation factory function
 */
forge.cipher.registerAlgorithm(name: string, algorithm: () => CipherAlgorithm): void;

/**
 * Get registered cipher algorithm
 * @param name - Algorithm name
 * @returns Algorithm factory function or null
 */
forge.cipher.getAlgorithm(name: string): (() => CipherAlgorithm) | null;

/**
 * Registry of all cipher algorithms
 */
forge.cipher.algorithms: {[name: string]: () => CipherAlgorithm};

interface CipherAlgorithm {
  initialize(options: any): void;
  encryptBlock(input: number[], output: number[]): void;
  decryptBlock(input: number[], output: number[]): void;
}

Low-Level Cipher Modes

Direct access to cipher mode implementations for advanced use cases.

/**
 * Electronic Codebook (ECB) mode - DO NOT USE for production (insecure)
 * @param options - Configuration options including cipher and blockSize
 * @returns ECB mode instance
 */
forge.cipher.modes.ecb(options: {cipher: CipherAlgorithm, blockSize?: number}): CipherMode;

/**
 * Cipher Block Chaining (CBC) mode
 * @param options - Configuration options including cipher and blockSize
 * @returns CBC mode instance
 */
forge.cipher.modes.cbc(options: {cipher: CipherAlgorithm, blockSize?: number}): CipherMode;

/**
 * Cipher Feedback (CFB) mode
 * @param options - Configuration options including cipher and blockSize
 * @returns CFB mode instance
 */
forge.cipher.modes.cfb(options: {cipher: CipherAlgorithm, blockSize?: number}): CipherMode;

/**
 * Output Feedback (OFB) mode  
 * @param options - Configuration options including cipher and blockSize
 * @returns OFB mode instance
 */
forge.cipher.modes.ofb(options: {cipher: CipherAlgorithm, blockSize?: number}): CipherMode;

/**
 * Counter (CTR) mode
 * @param options - Configuration options including cipher and blockSize
 * @returns CTR mode instance
 */
forge.cipher.modes.ctr(options: {cipher: CipherAlgorithm, blockSize?: number}): CipherMode;

/**
 * Galois/Counter Mode (GCM) for authenticated encryption
 * @param options - Configuration options including cipher and blockSize
 * @returns GCM mode instance
 */
forge.cipher.modes.gcm(options: {cipher: CipherAlgorithm, blockSize?: number}): CipherMode;

interface CipherMode {
  name: string;
  cipher: CipherAlgorithm;
  blockSize: number;
  
  start(options: {iv?: ByteStringBuffer, additionalData?: string, tagLength?: number}): void;
  encrypt(input: ByteStringBuffer, output: ByteStringBuffer, finish?: boolean): boolean;
  decrypt(input: ByteStringBuffer, output: ByteStringBuffer, finish?: boolean): boolean;
  pad?(input: ByteStringBuffer, options: any): boolean;
  unpad?(output: ByteStringBuffer, options: any): boolean;
}

Error Handling

Common error conditions when using symmetric ciphers.

try {
  const cipher = forge.cipher.createCipher('AES-CBC', key);
  cipher.start({iv: iv});
  cipher.update(forge.util.createBuffer(data));
  
  if (!cipher.finish()) {
    throw new Error('Cipher operation failed - possibly incorrect padding');
  }
  
  const result = cipher.output.getBytes();
} catch (error) {
  // Handle errors:
  // - 'Unsupported algorithm' for unknown cipher names
  // - Invalid key length for the chosen algorithm  
  // - Missing or invalid IV for modes that require it
  // - Padding errors during decryption
  // - Authentication failures for GCM mode
  console.error('Cipher operation failed:', error.message);
}

docs

asn1.md

asymmetric-cryptography.md

index.md

logging.md

message-digests.md

network-http.md

pkcs.md

pki.md

random.md

symmetric-encryption.md

tls.md

utilities.md

web-forms.md

tile.json