AES Decrypt

Category: Symmetric Ciphers · Node Type ID: symmetric-aes-decrypt

Decrypts ciphertext using NIST AES (128/192/256-bit)

Overview

Decrypts ciphertext produced by AES Encrypt using NIST AES (FIPS 197) with a 128-, 192-, or 256-bit key (or 32/64-byte double key in XTS mode).

In AEAD modes (GCM and CCM), the node verifies the required 16-byte Auth Tag against the ciphertext, Nonce, and optional AAD before releasing any plaintext; if the tag does not match, execution halts with AUTH_TAG_MISMATCH. Similarly, in KW (Key Wrap) mode, the 64-bit integrity check value (0xA6A6A6A6A6A6A6A6) is verified before unwrapping. Note that in ECB/CBC modes, Zero padding is intentionally excluded from automatic unpadding because trailing 0x00 data bytes cannot be unambiguously distinguished from padding (use Block Unpadder or Byte Slicer if needed).

When to Use

Decrypting and authenticating AES-GCM or AES-CCM ciphertexts and verifying tag integrity.
Decrypting CBC, CTR, ECB, CFB, OFB, XTS, or RFC 3394 Key Wrap (KW) payloads.

Parameter Configuration

Parameter (ID)	Type & Default	Visibility Condition	Description & Options
Cipher Mode `mode`	`select` Default: `ECB`	Always visible	Must match the Cipher Mode used during encryption. Controls which ports (`IV` vs. `Nonce`/`Auth Tag`/`AAD`) and padding options are visible. See Block Cipher Modes for full details. `ECB`: ECB (Electronic Codebook) `CBC`: CBC (Cipher Block Chaining) `GCM`: GCM (AEAD) `CCM`: CCM (AEAD) `CTR`: CTR (Counter Mode) `CFB`: CFB (Cipher Feedback) `OFB`: OFB (Output Feedback) `XTS`: XTS (Tweakable) `KW`: KW (Key Wrap)
Padding (CBC/ECB) `padding`	`select` Default: `None`	Always visible	Block unpadding scheme removed after decryption in `ECB` and `CBC` modes (`PKCS7`, `ISO7816`, `ISO97971M3`, `ANSIX923`, or `None`). Only visible when `Cipher Mode` is `ECB` or `CBC`. See Padding Schemes for full details. `None`: None `ISO7816`: ISO/IEC 9797-1 Method 2 (ISO/IEC 7816-4) `ISO97971M3`: ISO/IEC 9797-1 Method 3 `PKCS7`: PKCS#7 (RFC 5652) `ANSIX923`: ANSI X9.23
Unify Errors `errorUnify`	`boolean` Default: `false` Supports Variable Reference (`$var`: `bool`)	Always visible	Replaces any built-in decryption/verification error with a single custom code and message when enabled.
Unified Error Code `errorUnifyCode`	`text` Default: `""` (empty) Supports Variable Reference (`$var`: `string`)	When `errorUnify` is `true`	Custom error code emitted when Unify Errors is enabled.
Unified Error Message `errorUnifyMessage`	`text` Default: `""` (empty) Supports Variable Reference (`$var`: `string`)	When `errorUnify` is `true`	Custom error message emitted when Unify Errors is enabled.

Port I/O Specification

See Ports & Connections for general wiring rules, data type colors, and dynamic port creation.

Input Ports

Port Nature: Fixed Input Ports (6 total; conditionally visible ports depend on parameter settings as shown below).

Port Name	Port ID	Data Type	Required	Visibility Condition	Description
`Key`	`key`	`Bytes` (16/24/32B)	Required	Always visible	AES secret key (16, 24, or 32 bytes; 32 or 64 bytes in `XTS` mode).
`Ciphertext`	`ciphertext`	`Bytes`	Required	Always visible	Encrypted byte array (`Uint8Array`) to decrypt.
`IV`	`iv`	`Bytes` (16B)	Optional	When `mode` is `CBC` or `CTR` or `CFB` or `OFB` or `XTS`	16-byte IV, counter block, or XTS tweak used during encryption. Only visible in `CBC`, `CTR`, `CFB`, `OFB`, and `XTS` modes. Defaults to 16 zero bytes if unconnected.
`Nonce`	`nonce`	`Bytes` (12B)	Optional	When `mode` is `GCM` or `CCM`	12-byte AEAD nonce used during encryption. Only visible in `GCM` and `CCM` modes. Defaults to 12 zero bytes if unconnected.
`Auth Tag`	`tag`	`Bytes` (GCM/CCM)	Optional	When `mode` is `GCM` or `CCM`	Required 16-byte authentication tag to verify in `GCM` and `CCM` modes.
`AAD`	`aad`	`Bytes` (GCM/CCM)	Optional	When `mode` is `GCM` or `CCM`	Optional Additional Authenticated Data (must match the exact AAD bytes supplied during encryption). Only visible in `GCM` and `CCM` modes.

Output Ports

Port Nature: Fixed Output Ports (1 total).

Port Name	Port ID	Data Type	Visibility Condition	Description
`Plaintext`	`plaintext`	`Bytes`	Always visible	Recovered plaintext byte array (`Uint8Array`).

Error Cases

When any of the following conditions occurs at runtime, this node transitions to an ERROR state and downstream nodes connected to its outputs do not execute. Enabling Unify Errors (errorUnify) replaces all error codes below with your configured unified error code and message.

Error Code	Default Engine Message	Trigger Condition
`INVALID_KEY_LENGTH`	Invalid key length	Raised when `Key` length is not 16, 24, or 32 bytes (or 32/64 bytes in `XTS` mode).
`INVALID_IV_LENGTH`	Invalid IV length	Raised when a connected `IV` is not 16 bytes or a connected `Nonce` is not 12 bytes.
`INVALID_NONCE_LENGTH`	Invalid nonce length	Raised when a connected AEAD or stream-cipher `Nonce` is not 12 bytes (96 bits).
`INVALID_TAG_LENGTH`	Invalid authentication tag length	Raised when the connected AEAD `Auth Tag` is not 16 bytes (128 bits).
`AUTH_TAG_MISMATCH`	Authentication tag mismatch	Raised in `GCM` or `CCM` mode when authentication tag verification fails (wrong key, nonce, AAD, ciphertext, or tag).
`CIPHERTEXT_NOT_BLOCK_ALIGNED`	Ciphertext length is not a multiple of the block size	Raised in `ECB` or `CBC` mode when `Ciphertext` length is not a positive multiple of 16 bytes.
`INVALID_PADDING`	Invalid padding	Raised when the decrypted or input block's trailing bytes violate the structure of the selected padding standard.
`DATA_TOO_SHORT`	Data is too short	Raised when the input data is shorter than the minimum length required by the mode (e.g., < 16B in XTS or Key Wrap mode).

Examples

Verifying and Decrypting AES-256-GCM Ciphertext

Connect the outputs of AES Encrypt into AES Decrypt to verify round-trip recovery.

Set Cipher Mode to GCM (Authenticated Encryption).
Connect the same 32-byte Key, 12-byte Nonce, and AAD used during encryption, plus Ciphertext and Auth Tag.
The Plaintext port emits the verified original bytes.