ChaCha20-Poly1305 Decrypt

Category: Symmetric Ciphers · Node Type ID: symmetric-chacha20-poly1305-decrypt

RFC 8439 Authenticated Decryption with Additional Data (AEAD)

Overview

Verifies the 16-byte Poly1305 authentication tag and decrypts ciphertext using the IETF ChaCha20-Poly1305 AEAD construction (RFC 8439). If the tag fails verification against the ciphertext, AAD, Key, and Nonce, the node halts immediately with AUTH_TAG_MISMATCH without releasing unauthenticated plaintext.

When to Use

Verifying and decrypting ciphertexts produced by ChaCha20-Poly1305 Encrypt.

Parameter Configuration

Parameter (ID)	Type & Default	Visibility Condition	Description & Options
Unify Errors `errorUnify`	`boolean` Default: `false` Supports Variable Reference (`$var`: `bool`)	Always visible	Replaces built-in errors with a custom error code/message when enabled.
Unified Error Code `errorUnifyCode`	`text` Default: `""` (empty) Supports Variable Reference (`$var`: `string`)	When `errorUnify` is `true`	Custom error code when Unify Errors is enabled.
Unified Error Message `errorUnifyMessage`	`text` Default: `""` (empty) Supports Variable Reference (`$var`: `string`)	When `errorUnify` is `true`	Custom error message 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 (5 total).

Port Name	Port ID	Data Type	Required	Visibility Condition	Description
`Key`	`key`	`Bytes` (32B)	Required	Always visible	32-byte (256-bit) ChaCha20-Poly1305 secret key.
`Ciphertext`	`ciphertext`	`Bytes`	Required	Always visible	Encrypted byte array (`Uint8Array`) to decrypt.
`Nonce`	`nonce`	`Bytes` (12B)	Required	Always visible	12-byte (96-bit) IETF nonce used during encryption (defaults to 12 zero bytes if unconnected).
`Auth Tag`	`tag`	`Bytes` (16B)	Required	Always visible	Required 16-byte Poly1305 authentication tag to verify.
`AAD`	`aad`	`Bytes`	Optional	Always visible	Optional Additional Authenticated Data (must match the exact AAD bytes supplied during encryption).

Output Ports

Port Nature: Fixed Output Ports (1 total).

Port Name	Port ID	Data Type	Visibility Condition	Description
`Plaintext`	`plaintext`	`Bytes`	Always visible	Verified and decrypted 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` is not 32 bytes.
`INVALID_NONCE_LENGTH`	Invalid nonce length	Raised when a connected `Nonce` is not 12 bytes.
`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 when the 16-byte Poly1305 tag does not match or its length is not 16 bytes.

Examples

Verifying and Decrypting ChaCha20-Poly1305

Connect the outputs of ChaCha20-Poly1305 Encrypt to Decrypt.

Connect the 32-byte Key, 12-byte Nonce, Ciphertext, and 16-byte Auth Tag to ChaCha20-Poly1305 Decrypt.