Node.js crypto Module Guide

The crypto module provides cryptographic functionality including hashing, encryption, and secure random generation. Here's how to use it.

Hashing#

import crypto from 'node:crypto';

// Simple hash
function hash(data, algorithm = 'sha256') {
  return crypto.createHash(algorithm).update(data).digest('hex');
}

console.log(hash('Hello, World!')); // SHA-256 hash
console.log(hash('Hello, World!', 'md5')); // MD5 hash
console.log(hash('Hello, World!', 'sha512')); // SHA-512 hash

// Hash with different encodings
const hashBuffer = crypto.createHash('sha256')
  .update('Hello')
  .digest(); // Buffer

const hashBase64 = crypto.createHash('sha256')
  .update('Hello')
  .digest('base64'); // Base64 string

// Incremental hashing
const hasher = crypto.createHash('sha256');
hasher.update('Hello');
hasher.update(', ');
hasher.update('World!');
console.log(hasher.digest('hex'));

HMAC (Hash-based Message Authentication)#

import crypto from 'node:crypto';

// Create HMAC
function createHmac(data, secret, algorithm = 'sha256') {
  return crypto.createHmac(algorithm, secret)
    .update(data)
    .digest('hex');
}

const secret = 'my-secret-key';
const hmac = createHmac('message to authenticate', secret);
console.log(hmac);

// Verify HMAC
function verifyHmac(data, secret, providedHmac) {
  const calculated = createHmac(data, secret);
  return crypto.timingSafeEqual(
    Buffer.from(calculated),
    Buffer.from(providedHmac)
  );
}

Password Hashing#

import crypto from 'node:crypto';

// Hash password with salt (using scrypt)
async function hashPassword(password) {
  return new Promise((resolve, reject) => {
    const salt = crypto.randomBytes(16).toString('hex');

    crypto.scrypt(password, salt, 64, (err, derivedKey) => {
      if (err) reject(err);
      resolve(`${salt}:${derivedKey.toString('hex')}`);
    });
  });
}

// Verify password
async function verifyPassword(password, stored) {
  return new Promise((resolve, reject) => {
    const [salt, hash] = stored.split(':');

    crypto.scrypt(password, salt, 64, (err, derivedKey) => {
      if (err) reject(err);
      resolve(crypto.timingSafeEqual(
        Buffer.from(hash, 'hex'),
        derivedKey
      ));
    });
  });
}

// Usage
const hashed = await hashPassword('myPassword123');
console.log('Hashed:', hashed);

const isValid = await verifyPassword('myPassword123', hashed);
console.log('Valid:', isValid); // true

Random Bytes#

import crypto from 'node:crypto';

// Synchronous
const randomSync = crypto.randomBytes(32);
console.log(randomSync.toString('hex'));

// Asynchronous
crypto.randomBytes(32, (err, buffer) => {
  if (err) throw err;
  console.log(buffer.toString('hex'));
});

// Promise wrapper
function randomBytesAsync(size) {
  return new Promise((resolve, reject) => {
    crypto.randomBytes(size, (err, buffer) => {
      if (err) reject(err);
      else resolve(buffer);
    });
  });
}

// Generate random string
function randomString(length) {
  return crypto.randomBytes(Math.ceil(length / 2))
    .toString('hex')
    .slice(0, length);
}

// Random integer in range
function randomInt(min, max) {
  return crypto.randomInt(min, max);
}

console.log(randomInt(1, 100)); // Random number 1-99

UUID Generation#

import crypto from 'node:crypto';

// Generate UUID v4
const uuid = crypto.randomUUID();
console.log(uuid); // e.g., '1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed'

// Batch generation
function generateUUIDs(count) {
  return Array.from({ length: count }, () => crypto.randomUUID());
}

Symmetric Encryption (AES)#

import crypto from 'node:crypto';

const algorithm = 'aes-256-gcm';

// Encrypt
function encrypt(text, key) {
  const iv = crypto.randomBytes(16);
  const cipher = crypto.createCipheriv(algorithm, key, iv);

  let encrypted = cipher.update(text, 'utf8', 'hex');
  encrypted += cipher.final('hex');

  const authTag = cipher.getAuthTag();

  return {
    iv: iv.toString('hex'),
    encrypted,
    authTag: authTag.toString('hex'),
  };
}

// Decrypt
function decrypt(encrypted, key) {
  const decipher = crypto.createDecipheriv(
    algorithm,
    key,
    Buffer.from(encrypted.iv, 'hex')
  );

  decipher.setAuthTag(Buffer.from(encrypted.authTag, 'hex'));

  let decrypted = decipher.update(encrypted.encrypted, 'hex', 'utf8');
  decrypted += decipher.final('utf8');

  return decrypted;
}

// Usage
const key = crypto.randomBytes(32); // 256 bits
const message = 'Secret message';

const encrypted = encrypt(message, key);
console.log('Encrypted:', encrypted);

const decrypted = decrypt(encrypted, key);
console.log('Decrypted:', decrypted);

Asymmetric Encryption (RSA)#

import crypto from 'node:crypto';

// Generate key pair
function generateKeyPair() {
  return crypto.generateKeyPairSync('rsa', {
    modulusLength: 2048,
    publicKeyEncoding: {
      type: 'spki',
      format: 'pem',
    },
    privateKeyEncoding: {
      type: 'pkcs8',
      format: 'pem',
    },
  });
}

const { publicKey, privateKey } = generateKeyPair();

// Encrypt with public key
function rsaEncrypt(data, publicKey) {
  return crypto.publicEncrypt(
    {
      key: publicKey,
      padding: crypto.constants.RSA_PKCS1_OAEP_PADDING,
      oaepHash: 'sha256',
    },
    Buffer.from(data)
  );
}

// Decrypt with private key
function rsaDecrypt(encrypted, privateKey) {
  return crypto.privateDecrypt(
    {
      key: privateKey,
      padding: crypto.constants.RSA_PKCS1_OAEP_PADDING,
      oaepHash: 'sha256',
    },
    encrypted
  ).toString();
}

// Usage
const encrypted = rsaEncrypt('Secret', publicKey);
const decrypted = rsaDecrypt(encrypted, privateKey);

Digital Signatures#

import crypto from 'node:crypto';

// Sign data
function sign(data, privateKey) {
  const signer = crypto.createSign('RSA-SHA256');
  signer.update(data);
  return signer.sign(privateKey, 'hex');
}

// Verify signature
function verify(data, signature, publicKey) {
  const verifier = crypto.createVerify('RSA-SHA256');
  verifier.update(data);
  return verifier.verify(publicKey, signature, 'hex');
}

// Usage
const { publicKey, privateKey } = crypto.generateKeyPairSync('rsa', {
  modulusLength: 2048,
});

const data = 'Data to sign';
const signature = sign(data, privateKey);
const isValid = verify(data, signature, publicKey);
console.log('Signature valid:', isValid); // true

Key Derivation#

import crypto from 'node:crypto';

// PBKDF2
function deriveKeyPbkdf2(password, salt, iterations = 100000) {
  return new Promise((resolve, reject) => {
    crypto.pbkdf2(
      password,
      salt,
      iterations,
      64, // key length
      'sha512',
      (err, derivedKey) => {
        if (err) reject(err);
        else resolve(derivedKey);
      }
    );
  });
}

// Scrypt (more secure)
function deriveKeyScrypt(password, salt) {
  return new Promise((resolve, reject) => {
    crypto.scrypt(password, salt, 64, (err, derivedKey) => {
      if (err) reject(err);
      else resolve(derivedKey);
    });
  });
}

// Usage
const salt = crypto.randomBytes(16);
const key = await deriveKeyPbkdf2('password', salt);
console.log('Derived key:', key.toString('hex'));

Secure Token Generation#

import crypto from 'node:crypto';

// API token
function generateApiToken() {
  return crypto.randomBytes(32).toString('base64url');
}

// Session token
function generateSessionToken() {
  return crypto.randomBytes(48).toString('hex');
}

// Reset token with expiry
function generateResetToken() {
  const token = crypto.randomBytes(32).toString('hex');
  const expires = Date.now() + 3600000; // 1 hour
  const hash = crypto.createHash('sha256').update(token).digest('hex');

  return {
    token, // Send to user
    hash, // Store in database
    expires,
  };
}

// Verify reset token
function verifyResetToken(token, storedHash, expiry) {
  if (Date.now() > expiry) return false;
  const hash = crypto.createHash('sha256').update(token).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(hash),
    Buffer.from(storedHash)
  );
}

File Hashing#

import crypto from 'node:crypto';
import fs from 'node:fs';

// Hash file using streams
function hashFile(filePath, algorithm = 'sha256') {
  return new Promise((resolve, reject) => {
    const hash = crypto.createHash(algorithm);
    const stream = fs.createReadStream(filePath);

    stream.on('data', (data) => hash.update(data));
    stream.on('end', () => resolve(hash.digest('hex')));
    stream.on('error', reject);
  });
}

// Verify file integrity
async function verifyFileIntegrity(filePath, expectedHash) {
  const actualHash = await hashFile(filePath);
  return crypto.timingSafeEqual(
    Buffer.from(actualHash),
    Buffer.from(expectedHash)
  );
}

Best Practices#

Hashing:
✓ Use SHA-256 or SHA-512
✓ Use bcrypt/scrypt for passwords
✓ Always use salt
✓ Use timingSafeEqual for comparison

Encryption:
✓ Use AES-256-GCM for symmetric
✓ Use RSA-OAEP for asymmetric
✓ Generate random IVs
✓ Store keys securely

Random:
✓ Use crypto.randomBytes
✓ Use crypto.randomUUID for UUIDs
✓ Use crypto.randomInt for numbers
✓ Never use Math.random for security

Avoid:
✗ MD5 or SHA-1 for security
✗ Hardcoded keys/secrets
✗ ECB mode encryption
✗ Custom crypto implementations

The Node.js crypto module provides comprehensive cryptographic functionality. Use modern algorithms like SHA-256 for hashing, AES-256-GCM for encryption, and scrypt for password hashing. Always use cryptographically secure random number generation and never roll your own crypto. Store keys securely and use appropriate key lengths for your security requirements.