Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท crypto

AES-GCM authenticated encryption in Node.js

How AES-GCM works in Node.js: nonces, authentication tags, additional authenticated data, nonce reuse dangers and a complete encrypt and decrypt helper.

AES-GCM is an authenticated encryption mode. It does two jobs at once: it encrypts the data (confidentiality) and it produces a short authentication tag that proves the ciphertext, and optionally some extra header data, has not been changed (integrity and authenticity). Anyone who modifies even one bit causes decryption to fail.

In Node.js you use it through createCipheriv() and createDecipheriv() with aes-128-gcm, aes-192-gcm or aes-256-gcm. Three values matter: a secret key, a unique nonce (the iv argument) and the tag.

Try it

Node.js A reusable encrypt and decrypt pair

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 Additional authenticated data (AAD)

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.

How it works

GCM turns AES into a counter-mode stream cipher, which is why the ciphertext has the same length as the plaintext and no padding is needed. At the same time it runs a polynomial hash (GHASH) over the optional AAD and the ciphertext, and encrypts the result into the tag. During decryption the tag is recomputed and compared; a mismatch makes final() throw.

Key. 16, 24 or 32 bytes, matching AES-128, AES-192 or AES-256. Generate it with randomBytes() or derive it with scrypt/hkdf.

Nonce. 12 bytes (96 bits) is the size GCM is designed for; other sizes work but are processed differently and are not recommended. The nonce is public. It must never repeat for the same key.

Tag. 16 bytes by default. Shorter tags are allowed by the standard but weaker; fix the length on decryption with authTagLength.

AAD. Data that is sent unencrypted but must not be altered: a message header, a user ID, a version number. Binding the context this way stops an attacker from moving a valid ciphertext to a different context.

Usage notes

  • Nonce reuse is catastrophic. Two messages encrypted with the same key and nonce reveal the XOR of the plaintexts and let an attacker forge tags. Random 12-byte nonces are safe up to about 2**32 messages per key; beyond that, rotate keys or use a counter.
  • Verify before use. decipher.update() returns plaintext before the tag has been checked. Only trust it after final() returns without throwing; on failure, discard everything.
  • getAuthTag() only after final() on the encrypting side; setAuthTag() before final() on the decrypting side.
  • Store everything needed to decrypt: nonce, tag and ciphertext (plus the AAD you chose). A fixed layout like the one above is easy to parse.
  • Large messages. GCM is limited to about 64 GiB of plaintext per nonce. For big files, encrypt in chunks, each with its own nonce.
  • Alternatives. chacha20-poly1305 offers the same guarantees and is fast on devices without AES hardware support; aes-256-ocb and CCM exist but are less common.
  • GCM is not a password scheme. The key must be random bytes; do not pass a password directly.