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.
import { createCipheriv, randomBytes } from 'node:crypto'; const key = randomBytes(32); const iv = randomBytes(12); const cipher = createCipheriv('aes-256-gcm', key, iv);
Try it
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.
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
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 afterfinal(). - Call
update()as often as needed, and concatenate every returned chunk, including the one fromfinal(). - Keys are bytes, not passwords. Derive them from passwords with
crypto.scrypt(), or generate them withcrypto.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.