Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท crypto

Node.js crypto.createDecipheriv() function

Reference for crypto.createDecipheriv() in Node.js: decrypting AES data with the right key and IV, setAuthTag for GCM, padding errors and detecting tampering.

crypto.createDecipheriv(algorithm, key, iv[, options]) returns a Decipher object, the mirror image of createCipheriv(). You pass ciphertext to decipher.update() and finish with decipher.final(), then join the chunks to get the plaintext. Like the cipher, it is also a transform stream.

You must supply the same algorithm, key and IV that were used to encrypt. With authenticated modes such as GCM you also supply the authentication tag with setAuthTag() before final(); if the data or tag was altered, final() throws, and you must discard any plaintext you already read.

NODE
import { createDecipheriv } from 'node:crypto';

const decipher = createDecipheriv('aes-256-cbc', key, iv);
const plain = Buffer.concat([decipher.update(data), decipher.final()]);

Try it

Node.js Round trip with AES-CBC

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 Tampering and wrong keys are detected (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.

Syntax

NODE
crypto.createDecipheriv(algorithm, key, iv, options?): Decipheriv
decipher.update(data, inputEncoding?, outputEncoding?): Buffer | string
decipher.final(outputEncoding?): Buffer | string
decipher.setAutoPadding(autoPadding = true): this
decipher.setAuthTag(buffer, encoding?): this   // before final()
decipher.setAAD(buffer, options?): this
Name Description
algorithm Same cipher name used for encryption.
key Same raw key (string, buffer, typed array, DataView or secret KeyObject).
iv Same initialization vector.
options.authTagLength Expected tag length in bytes for CCM, OCB and ChaCha20-Poly1305; for GCM it limits accepted tag lengths. Always pass it for GCM if tags might be truncated.

Returns: a Decipheriv object (also a Transform stream).

Errors: the creation errors are the same as for createCipheriv(). final() throws Unsupported state or unable to authenticate data for a bad GCM tag or altered data, and a bad decrypt error (ERR_OSSL_BAD_DECRYPT) for CBC when padding is invalid, which usually means a wrong key or IV.

Usage notes

  • Check authentication before using plaintext. In GCM, update() returns plaintext before the tag is verified. Do not act on it until final() has succeeded.
  • Set the tag before final(). Calling setAuthTag() after final() has no effect, and the call must come before or between update() calls.
  • Limit the tag length. Pass authTagLength: 16 so an attacker cannot supply a very short tag that is easier to forge.
  • A "bad decrypt" is not proof of a wrong key in CBC: padding errors can also come from corrupted data. CBC has no integrity check, and distinguishing padding errors for attackers enables padding-oracle attacks, so return one generic error to clients.
  • Store the IV and tag with the ciphertext. A common layout is iv || ciphertext || tag.
  • Single use. Create a new Decipher for every message.
  • Encoding arguments. If you pass an outputEncoding such as 'utf8', update() and final() return strings. Mixing strings and buffers when concatenating is a common source of corrupted multi-byte characters; use buffers and decode once at the end.