Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท crypto

Node.js crypto.createCipheriv() function

Reference for crypto.createCipheriv() in Node.js: symmetric encryption with AES, key and IV sizes, update() and final(), padding, streams, GCM auth tags and errors.

crypto.createCipheriv(algorithm, key, iv[, options]) returns a Cipher object that encrypts data with a symmetric algorithm such as AES. You feed plaintext to it with cipher.update() and finish with cipher.final(); the pieces you collect together make up the ciphertext. A Cipher is also a transform stream, so you can pipe data through it.

The iv in the name is the initialization vector (or nonce). It makes the same key and plaintext produce different ciphertexts each time. Prefer an authenticated mode such as aes-256-gcm, which detects tampering; see AES-GCM.

NODE
import { createCipheriv, randomBytes } from 'node:crypto';

const key = randomBytes(32);
const iv = randomBytes(12);
const cipher = createCipheriv('aes-256-gcm', key, iv);

Try it

Node.js Encrypt with AES-256-GCM

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js AES-CBC, padding and size errors

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
crypto.createCipheriv(algorithm, key, iv, options?): Cipheriv
cipher.update(data, inputEncoding?, outputEncoding?): Buffer | string
cipher.final(outputEncoding?): Buffer | string
cipher.setAutoPadding(autoPadding = true): this
cipher.getAuthTag(): Buffer              // GCM, CCM, OCB, ChaCha20-Poly1305
cipher.setAAD(buffer, options?): this    // authenticated modes
Name Description
algorithm Cipher name, for example 'aes-256-gcm', 'aes-128-cbc', 'aes-256-ctr' or 'chacha20-poly1305'. List them with crypto.getCiphers().
key Raw key as string, Buffer, typed array, DataView, or a secret KeyObject. Its length must match the algorithm (32 bytes for AES-256).
iv Initialization vector, or null for ciphers that take none. 16 bytes for CBC and CTR, 12 bytes recommended for GCM.
options.authTagLength Tag length in bytes for CCM, OCB and ChaCha20-Poly1305 (required for CCM and OCB); GCM defaults to 16.
options.plaintextLength CCM only: total plaintext length in bytes.

Returns: a Cipheriv object. It is also a Transform stream.

Errors: ERR_CRYPTO_INVALID_KEYLEN for a wrong key length, ERR_CRYPTO_INVALID_IV for a wrong IV length, ERR_CRYPTO_UNKNOWN_CIPHER for an unknown name (message "Unknown cipher"), and ERR_OSSL_WRONG_FINAL_BLOCK_LENGTH from final() when padding is disabled and the data is not block-aligned.

Usage notes

  • Never reuse an IV with the same key. For GCM this breaks both confidentiality and authentication. Generate a fresh random 12-byte IV for each message and store it next to the ciphertext; it is not secret.
  • Prefer authenticated encryption. CBC and CTR give no integrity protection, so an attacker can flip bits undetected. Use GCM or ChaCha20-Poly1305, or add an HMAC (encrypt-then-MAC).
  • Always call final(). It flushes the last block and, for GCM, completes the tag. getAuthTag() works only after final().
  • Call update() as often as needed, and concatenate every returned chunk, including the one from final().
  • Keys are bytes, not passwords. Derive them from passwords with crypto.scrypt(), or generate them with crypto.randomBytes().
  • A cipher object is single use. After final() you must create a new one.
  • Streaming. For files, pipeline(readStream, cipher, writeStream) encrypts without loading everything into memory.