Security

Payload Encryption & Decryption

Secure AES-256-GCM payload encryption and decryption sandbox guide

View as Markdown

To ensure absolute confidentiality and data integrity, webhook events and session results delivered by INFONITE can be configured with payload encryption. This page details both the encryption and decryption processes used to protect communication.

We use AES-256-GCM (Galois/Counter Mode) encryption. All encrypted payloads are returned as a Base64-encoded string prefixed with aes::.

The Encrypted Format

The encrypted payload is delivered as a string prefixed with aes:: followed by the Base64-encoded binary data.

Prefixaes::(Discard first)
+
Base64 Encoded EnvelopeU2FsdGVkX19…(Decode to raw binary)
IV / NonceFirst 12 bytes
CiphertextMiddle bytes
Auth TagLast 16 bytes

The raw byte layout after decoding the Base64 portion follows a strict concatenation sequence:

ComponentSizeDescription
IV (Nonce)12 bytesCryptographically secure random initialization vector.
CiphertextVariable bytesThe actual encrypted JSON string.
Authentication Tag16 bytesGMAC integrity and authenticity validation tag.

Encryption & Decryption Workflows

Here is the technical walkthrough for implementing the cryptography pipelines.

Encryption Walkthrough

Encryption Walkthrough
1

Generate IV: Create a cryptographically secure random 12-byte initialization vector (nonce).

2

Encrypt: Encrypt the plaintext payload using the AES-256-GCM algorithm with your allocated 32-byte key and the generated IV.

3

Assemble Envelope: Concatenate the IV (12 bytes), the resulting ciphertext (variable bytes), and the 16-byte authentication tag returned by the cipher.

4

Encode and Prefix: Base64-encode the concatenated byte block and prepended with the aes:: prefix.

Decryption Walkthrough

Decryption Walkthrough
1

Remove Prefix: Strip the aes:: prefix from the string.

2

Decode Base64: Decode the remaining Base64-encoded string to extract the raw bytes.

3

Extract Payload Parts:

  • IV (Initialization Vector): Extract the first 12 bytes.
  • Tag (Authentication Tag): Extract the last 16 bytes.
  • Ciphertext: Extract the middle bytes (everything between the first 12 bytes and the last 16 bytes).
4

Decrypt: Decrypt the Ciphertext using the AES-256-GCM algorithm with your allocated Session aes_key (configured during Create Session), the extracted IV, and the Tag.

Interactive Cryptography Sandbox

Test your GCM encryption and decryption logic directly in this sandbox tool. Toggle the switcher below to change between the Encrypt and Decrypt pipelines.

AES-256-GCM Playground
AES Key (32-byte Base64)
Plaintext JSON to Encrypt
Encrypted Payload (prefixed with aes::)
Output Results
Output will appear here…

Implementation Code Examples

Select your preferred programming language tab below to copy production-ready code examples matching this AES-256-GCM specification.

1const crypto = require('node:crypto');
2
3/**
4 * Encrypt plaintext using AES-256-GCM and return the base64-encoded string prefixed with "aes::".
5 * @param {Buffer} key - 32-byte AES key
6 * @param {Buffer} plaintext - Data to encrypt
7 * @returns {string} Encrypted payload prefixed with "aes::"
8 */
9function encryptGcm(key, plaintext) {
10  if (key.length !== 32) throw new Error('Key must be exactly 32 bytes');
11  const iv = crypto.randomBytes(12);
12  const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
13  const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
14  const tag = cipher.getAuthTag();
15  const envelope = Buffer.concat([iv, ciphertext, tag]);
16  return `aes::${envelope.toString('base64')}`;
17}
18
19/**
20 * Decrypt an aes:: prefixed Base64 string using AES-256-GCM.
21 * @param {Buffer} key - 32-byte AES key
22 * @param {string} payloadB64 - Encrypted payload prefixed with "aes::"
23 * @returns {Buffer} Decrypted plaintext bytes
24 */
25function decryptGcm(key, payloadB64) {
26  if (key.length !== 32) throw new Error('Key must be exactly 32 bytes');
27  const blob = Buffer.from(payloadB64.replace(/^aes::/, ''), 'base64');
28  const iv = blob.subarray(0, 12);
29  const tag = blob.subarray(blob.length - 16);
30  const ciphertext = blob.subarray(12, blob.length - 16);
31  
32  const decipher = crypto.createDecipheriv('aes-256-gcm', key, iv);
33  decipher.setAuthTag(tag);
34  
35  return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
36}
37
38// Example usage:
39const key = Buffer.from('9127m7kfzkNxS14A2U71lEzcyaqv9K5xDLtKuFTg+84=', 'base64');
40
41// Encrypt example
42const secretData = Buffer.from(JSON.stringify({ test: 'You got it!!!' }), 'utf8');
43const encrypted = encryptGcm(key, secretData);
44console.log('Encrypted Payload:', encrypted);
45
46// Decrypt example
47const decrypted = decryptGcm(key, encrypted);
48console.log('Decrypted Plaintext:', decrypted.toString('utf8'));