ChaCha20-Poly1305 Encrypt

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

RFC 8439 Authenticated Encryption with Additional Data (AEAD)

Overview

Encrypts arbitrary-length plaintext and computes a 16-byte authentication tag using the IETF ChaCha20-Poly1305 Authenticated Encryption with Additional Data (AEAD) construction standardized in RFC 8439.

Combines Daniel J. Bernstein's 20-round ChaCha20 ARX stream cipher (using a 256-bit / 32-byte key and 96-bit / 12-byte nonce) with a one-time Poly1305 authenticator key derived from block counter 0. Because ChaCha20-Poly1305 relies only on 32-bit addition, XOR, and rotation, it achieves high speed and constant-time immunity to cache-timing attacks even on platforms without dedicated AES hardware instructions.

When to Use

Encrypting messages in modern protocols such as TLS 1.3, WireGuard, SSH, QUIC, and mobile/embedded messaging where software constant-time AEAD is preferred.
Validating RFC 8439 §2.8.2 AEAD test vectors.

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 (4 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.
`Plaintext`	`plaintext`	`Bytes`	Required	Always visible	Plaintext byte array (`Uint8Array`) of any length to encrypt (no block padding required).
`Nonce`	`nonce`	`Bytes` (12B)	Optional	Always visible	12-byte (96-bit) IETF nonce. Defaults to 12 zero bytes if unconnected (never reuse a key+nonce pair in production).
`AAD`	`aad`	`Bytes`	Optional	Always visible	Optional Additional Authenticated Data (`Uint8Array`) authenticated by the Poly1305 MAC without being encrypted.

Output Ports

Port Nature: Fixed Output Ports (2 total).

Port Name	Port ID	Data Type	Visibility Condition	Description
`Ciphertext`	`ciphertext`	`Bytes`	Always visible	Encrypted output bytes (`Uint8Array`, exact same byte length as `Plaintext`).
`Auth Tag`	`tag`	`Bytes` (16B)	Always visible	16-byte (128-bit) Poly1305 authentication tag.

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 exactly 32 bytes.
`INVALID_NONCE_LENGTH`	Invalid nonce length	Raised when a connected `Nonce` is not exactly 12 bytes.

Examples

Authenticated Encryption with ChaCha20-Poly1305

Encrypt a message with a 32-byte key and 12-byte nonce.

Connect a 32-byte key to Key, a 12-byte nonce to Nonce, and your payload to Plaintext.
Wire Ciphertext and Auth Tag to ChaCha20-Poly1305 Decrypt.