Node.js Crypto Module Guide

The crypto module provides cryptographic functionality for hashing, encryption, and secure random numbers.

Hashing#

const crypto = require('crypto');

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

console.log(hash('hello world'));
// a591a6d40bf420404a011733cfb7b190d62c65bf0bcda32b57b277d9ad9f146e

// Different algorithms
console.log(hash('hello', 'md5'));    // 5d41402abc4b2a76b9719d911017c592
console.log(hash('hello', 'sha1'));   // aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d
console.log(hash('hello', 'sha512')); // 9b71d224bd62f...

// Hash file
const fs = require('fs');

function hashFile(filepath) {
  return new Promise((resolve, reject) => {
    const hash = crypto.createHash('sha256');
    const stream = fs.createReadStream(filepath);

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

// Streaming hash
async function hashLargeFile(filepath) {
  const hash = crypto.createHash('sha256');

  for await (const chunk of fs.createReadStream(filepath)) {
    hash.update(chunk);
  }

  return hash.digest('hex');
}

Password Hashing#

const crypto = require('crypto');

// Using scrypt (recommended)
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')}`);
    });
  });
}

async function verifyPassword(password, storedHash) {
  const [salt, hash] = storedHash.split(':');

  return new Promise((resolve, reject) => {
    crypto.scrypt(password, salt, 64, (err, derivedKey) => {
      if (err) reject(err);
      resolve(derivedKey.toString('hex') === hash);
    });
  });
}

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

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

// Using pbkdf2
function hashPasswordPbkdf2(password) {
  return new Promise((resolve, reject) => {
    const salt = crypto.randomBytes(16).toString('hex');

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

Symmetric Encryption#

const crypto = require('crypto');

// AES-256-GCM encryption
function encrypt(text, key) {
  const iv = crypto.randomBytes(16);
  const cipher = crypto.createCipheriv('aes-256-gcm', 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'),
  };
}

function decrypt(encryptedData, key) {
  const decipher = crypto.createDecipheriv(
    'aes-256-gcm',
    key,
    Buffer.from(encryptedData.iv, 'hex')
  );

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

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

  return decrypted;
}

// Usage
const key = crypto.randomBytes(32); // 256 bits
const encrypted = encrypt('secret message', key);
const decrypted = decrypt(encrypted, key);
console.log(decrypted); // 'secret message'

// AES-256-CBC (simpler but no authentication)
function encryptCBC(text, key) {
  const iv = crypto.randomBytes(16);
  const cipher = crypto.createCipheriv('aes-256-cbc', key, iv);

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

  return `${iv.toString('hex')}:${encrypted}`;
}

function decryptCBC(encryptedText, key) {
  const [ivHex, encrypted] = encryptedText.split(':');
  const iv = Buffer.from(ivHex, 'hex');
  const decipher = crypto.createDecipheriv('aes-256-cbc', key, iv);

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

  return decrypted;
}

HMAC#

const crypto = require('crypto');

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

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

// Usage: API request signing
function signRequest(method, path, body, secret) {
  const timestamp = Date.now().toString();
  const message = `${method}:${path}:${timestamp}:${JSON.stringify(body)}`;

  return {
    signature: createHmac(message, secret),
    timestamp,
  };
}

function verifyRequest(method, path, body, timestamp, signature, secret) {
  const message = `${method}:${path}:${timestamp}:${JSON.stringify(body)}`;
  return verifyHmac(message, secret, signature);
}

// Webhook verification
function verifyWebhook(payload, signature, secret) {
  const expectedSignature = createHmac(payload, secret);
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Random Values#

const crypto = require('crypto');

// Random bytes
const randomBytes = crypto.randomBytes(32);
console.log(randomBytes.toString('hex'));

// Random hex string
function randomHex(length) {
  return crypto.randomBytes(length).toString('hex');
}

// Random base64 string
function randomBase64(length) {
  return crypto.randomBytes(length).toString('base64');
}

// Random URL-safe string
function randomUrlSafe(length) {
  return crypto
    .randomBytes(length)
    .toString('base64')
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=/g, '');
}

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

// Secure token generation
function generateToken(length = 32) {
  return crypto.randomBytes(length).toString('hex');
}

// UUID v4 (use crypto.randomUUID in Node 14.17+)
function generateUUID() {
  if (crypto.randomUUID) {
    return crypto.randomUUID();
  }

  const bytes = crypto.randomBytes(16);
  bytes[6] = (bytes[6] & 0x0f) | 0x40;
  bytes[8] = (bytes[8] & 0x3f) | 0x80;

  const hex = bytes.toString('hex');
  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
}

Key Derivation#

const crypto = require('crypto');

// Derive key from password
function deriveKey(password, salt, keyLength = 32) {
  return new Promise((resolve, reject) => {
    crypto.scrypt(password, salt, keyLength, (err, derivedKey) => {
      if (err) reject(err);
      resolve(derivedKey);
    });
  });
}

// HKDF (Node.js 15+)
async function deriveKeyHKDF(secret, salt, info, keyLength = 32) {
  const key = await crypto.subtle.importKey(
    'raw',
    Buffer.from(secret),
    'HKDF',
    false,
    ['deriveBits']
  );

  const derived = await crypto.subtle.deriveBits(
    {
      name: 'HKDF',
      hash: 'SHA-256',
      salt: Buffer.from(salt),
      info: Buffer.from(info),
    },
    key,
    keyLength * 8
  );

  return Buffer.from(derived);
}

// Key stretching for encryption
async function createEncryptionKey(password) {
  const salt = crypto.randomBytes(16);
  const key = await deriveKey(password, salt, 32);

  return {
    key,
    salt: salt.toString('hex'),
  };
}

Digital Signatures#

const crypto = require('crypto');

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

// 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 } = generateKeyPair();
const message = 'Important message';
const signature = sign(message, privateKey);
const isValid = verify(message, signature, publicKey);
console.log(isValid); // true

// Ed25519 (faster, shorter keys)
function generateEd25519KeyPair() {
  return crypto.generateKeyPairSync('ed25519', {
    publicKeyEncoding: { type: 'spki', format: 'pem' },
    privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
  });
}

Practical Examples#

const crypto = require('crypto');

// Session token
function createSessionToken(userId) {
  const payload = JSON.stringify({
    userId,
    created: Date.now(),
  });

  const token = crypto.randomBytes(32).toString('hex');
  const hash = crypto
    .createHash('sha256')
    .update(payload + token)
    .digest('hex');

  return `${Buffer.from(payload).toString('base64')}.${hash}`;
}

// Password reset token
function createResetToken() {
  const token = crypto.randomBytes(32).toString('hex');
  const hash = crypto.createHash('sha256').update(token).digest('hex');

  return {
    token, // Send to user
    hash,  // Store in database
    expires: Date.now() + 3600000, // 1 hour
  };
}

// Checksum for file integrity
async function createChecksum(filepath) {
  const hash = crypto.createHash('sha256');

  for await (const chunk of require('fs').createReadStream(filepath)) {
    hash.update(chunk);
  }

  return hash.digest('hex');
}

// Encrypt configuration
function encryptConfig(config, masterKey) {
  const key = crypto.scryptSync(masterKey, 'salt', 32);
  const iv = crypto.randomBytes(16);
  const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);

  const encrypted = Buffer.concat([
    cipher.update(JSON.stringify(config), 'utf8'),
    cipher.final(),
  ]);

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

Best Practices#

Algorithms:
✓ Use scrypt or Argon2 for passwords
✓ Use AES-256-GCM for encryption
✓ Use SHA-256 or SHA-512 for hashing
✓ Use HMAC for message authentication

Security:
✓ Use crypto.randomBytes for tokens
✓ Use timing-safe comparison
✓ Generate unique IVs/salts
✓ Store salts with hashes

Key Management:
✓ Use environment variables
✓ Rotate keys periodically
✓ Use key derivation functions
✓ Never hardcode secrets

Avoid:
✗ MD5 or SHA1 for security
✗ ECB mode for encryption
✗ Predictable IVs or salts
✗ Rolling your own crypto

The Node.js crypto module provides comprehensive cryptographic functionality. Use scrypt for password hashing, AES-GCM for encryption, and HMAC for authentication. Always use secure random generation for tokens and keys. Follow best practices for algorithm selection and key management.