AES-GCM Decryption

Overview

AES-GCM decryption reverses the encryption process while verifying the authentication tag. This ensures that:

Ciphertext hasn’t been tampered with (integrity)
Correct key and nonce were used (authentication)
AAD matches encryption (if used)

Decryption fails completely if authentication fails - no partial plaintext is returned.

Decryption Operation

Basic Decryption

import * as AesGcm from '@tevm/voltaire/crypto/aesgcm';

// Decrypt data (using same key and nonce from encryption)
try {
  const decrypted = await AesGcm.decrypt(ciphertext, key, nonce);
  const message = new TextDecoder().decode(decrypted);
  console.log('Decrypted:', message);
} catch (error) {
  console.error('Decryption failed:', error);
  // Could be: wrong key, wrong nonce, tampered data, or corrupted ciphertext
}

How It Works

AES-GCM decryption involves three main steps:

Separate Components
- Extract authentication tag (last 16 bytes)
- Extract ciphertext (remaining bytes)
Verify Authentication Tag
- Recompute tag using ciphertext, AAD, nonce, and key
- Compare computed tag with provided tag (constant-time)
- Fail immediately if tags don’t match
Decrypt Ciphertext (only if authentication passes)
- Generate keystream using counter mode
- XOR keystream with ciphertext to produce plaintext
- Return plaintext

Critical: Authentication is verified BEFORE decryption to prevent timing attacks and ensure tampered data is never returned.

Parameters

Ciphertext (Required)

The encrypted data including the 16-byte authentication tag:

// Minimum length: 16 bytes (just the tag, for empty plaintext)
const ciphertext = new Uint8Array([
  /* encrypted data */,
  /* 16-byte tag */
]);

// Decrypt
const plaintext = await AesGcm.decrypt(ciphertext, key, nonce);

Format:

┌─────────────────┬──────────────────┐
│   Ciphertext    │  Auth Tag (16B)  │
└─────────────────┴──────────────────┘

Error if too short:

const tooShort = new Uint8Array(15); // Less than 16 bytes

try {
  await AesGcm.decrypt(tooShort, key, nonce);
} catch (error) {
  console.error(error); // "Ciphertext too short to contain authentication tag"
}

Key (Required)

Must be the same key used for encryption:

const key = await AesGcm.generateKey(256);

// Encrypt
const ciphertext = await AesGcm.encrypt(plaintext, key, nonce);

// Decrypt with SAME key
const decrypted = await AesGcm.decrypt(ciphertext, key, nonce);

// WRONG: Different key
const wrongKey = await AesGcm.generateKey(256);
await AesGcm.decrypt(ciphertext, wrongKey, nonce); // Throws DecryptionError

Nonce (Required)

Must be the same nonce used for encryption:

// Encrypt
const nonce = AesGcm.generateNonce();
const ciphertext = await AesGcm.encrypt(plaintext, key, nonce);

// Store nonce with ciphertext
const stored = new Uint8Array(nonce.length + ciphertext.length);
stored.set(nonce, 0);
stored.set(ciphertext, nonce.length);

// Later: Extract nonce and decrypt
const extractedNonce = stored.slice(0, AesGcm.NONCE_SIZE);
const extractedCiphertext = stored.slice(AesGcm.NONCE_SIZE);
const decrypted = await AesGcm.decrypt(extractedCiphertext, key, extractedNonce);

CRITICAL: Nonce must be exactly 12 bytes (96 bits)

const wrongNonce = Bytes16(); // Wrong size!

try {
  await AesGcm.decrypt(ciphertext, key, wrongNonce);
} catch (error) {
  console.error(error); // "Nonce must be 12 bytes, got 16"
}

Additional Authenticated Data (Optional)

If AAD was used during encryption, the exact same AAD must be provided for decryption:

// Encrypt with AAD
const aad = new TextEncoder().encode('metadata');
const ciphertext = await AesGcm.encrypt(plaintext, key, nonce, aad);

// Decrypt with SAME AAD
const decrypted = await AesGcm.decrypt(ciphertext, key, nonce, aad);

// WRONG: Different AAD
const wrongAAD = new TextEncoder().encode('different');
await AesGcm.decrypt(ciphertext, key, nonce, wrongAAD); // Throws DecryptionError

// WRONG: Missing AAD
await AesGcm.decrypt(ciphertext, key, nonce); // Throws DecryptionError

AAD is part of authentication - any change (including omission) causes decryption to fail.

Error Handling

Authentication Failures

Decryption throws DecryptionError if authentication fails:

try {
  const decrypted = await AesGcm.decrypt(ciphertext, key, nonce);
  // Success - data is authentic
} catch (error) {
  if (error.name === 'DecryptionError') {
    console.error('Authentication failed:', error.message);
    // Possible causes:
    // - Wrong key
    // - Wrong nonce
    // - Wrong AAD
    // - Tampered ciphertext
    // - Corrupted data
  }
}

Common Failure Scenarios

1. Wrong key:

const key1 = await AesGcm.generateKey(256);
const key2 = await AesGcm.generateKey(256);

const ciphertext = await AesGcm.encrypt(plaintext, key1, nonce);

await AesGcm.decrypt(ciphertext, key2, nonce); // Throws DecryptionError

2. Wrong nonce:

const nonce1 = AesGcm.generateNonce();
const nonce2 = AesGcm.generateNonce();

const ciphertext = await AesGcm.encrypt(plaintext, key, nonce1);

await AesGcm.decrypt(ciphertext, key, nonce2); // Throws DecryptionError

3. Tampered ciphertext:

const ciphertext = await AesGcm.encrypt(plaintext, key, nonce);

// Modify ciphertext
const tampered = new Uint8Array(ciphertext);
tampered[0] ^= 1; // Flip one bit

await AesGcm.decrypt(tampered, key, nonce); // Throws DecryptionError

4. Tampered authentication tag:

const ciphertext = await AesGcm.encrypt(plaintext, key, nonce);

// Modify tag (last 16 bytes)
const tampered = new Uint8Array(ciphertext);
tampered[ciphertext.length - 1] ^= 1; // Flip one bit in tag

await AesGcm.decrypt(tampered, key, nonce); // Throws DecryptionError

5. Wrong AAD:

const aad1 = new TextEncoder().encode('metadata1');
const aad2 = new TextEncoder().encode('metadata2');

const ciphertext = await AesGcm.encrypt(plaintext, key, nonce, aad1);

await AesGcm.decrypt(ciphertext, key, nonce, aad2); // Throws DecryptionError

Error Messages

// Ciphertext too short
"Ciphertext too short to contain authentication tag"

// Wrong nonce length
"Nonce must be 12 bytes, got {length}"

// Authentication failed
"Decryption failed (invalid key, nonce, or corrupted data): ..."

Security Properties

Constant-Time Verification

Tag verification is performed in constant time to prevent timing attacks:

// WebCrypto API implements constant-time comparison
// Attackers cannot learn anything from execution time

const tampered1 = new Uint8Array(ciphertext);
tampered1[0] ^= 1; // First byte of ciphertext

const tampered2 = new Uint8Array(ciphertext);
tampered2[ciphertext.length - 1] ^= 1; // Last byte of tag

// Both fail in approximately the same time
await AesGcm.decrypt(tampered1, key, nonce); // Throws
await AesGcm.decrypt(tampered2, key, nonce); // Throws

All-or-Nothing Decryption

If authentication fails, no plaintext is returned - not even partial data:

const plaintext = new TextEncoder().encode('Secret message with sensitive data');
const ciphertext = await AesGcm.encrypt(plaintext, key, nonce);

// Tamper with one byte
const tampered = new Uint8Array(ciphertext);
tampered[5] ^= 1;

try {
  const decrypted = await AesGcm.decrypt(tampered, key, nonce);
  // Never reached
} catch (error) {
  // No partial plaintext available
  // Attacker learns nothing about the message
}

This prevents padding oracle attacks and ensures data integrity.

Advanced Usage

Batch Decryption

Decrypt multiple messages in parallel:

async function decryptBatch(encrypted, key) {
  const decrypted = await Promise.all(
    encrypted.map(async ({ nonce, ciphertext }) => {
      try {
        const n = new Uint8Array(nonce);
        const ct = new Uint8Array(ciphertext);
        const plaintext = await AesGcm.decrypt(ct, key, n);

        return {
          success: true,
          plaintext: new TextDecoder().decode(plaintext)
        };
      } catch (error) {
        return {
          success: false,
          error: error.message
        };
      }
    })
  );

  return decrypted;
}

// Usage
const results = await decryptBatch(encryptedMessages, key);

results.forEach((result, i) => {
  if (result.success) {
    console.log(`Message ${i}:`, result.plaintext);
  } else {
    console.error(`Message ${i} failed:`, result.error);
  }
});

Extract and Decrypt

Parse stored format and decrypt:

// Stored format: [12-byte nonce][ciphertext][16-byte tag]
async function extractAndDecrypt(stored, key) {
  // Validate minimum length
  if (stored.length < AesGcm.NONCE_SIZE + AesGcm.TAG_SIZE) {
    throw new Error('Invalid stored data: too short');
  }

  // Extract components
  const nonce = stored.slice(0, AesGcm.NONCE_SIZE);
  const ciphertext = stored.slice(AesGcm.NONCE_SIZE);

  // Decrypt
  return await AesGcm.decrypt(ciphertext, key, nonce);
}

// Usage
const stored = loadFromDatabase();
const plaintext = await extractAndDecrypt(stored, key);

Verify Without Decrypting

Check if decryption would succeed without actually decrypting:

async function verifyAuthenticity(ciphertext, key, nonce, aad) {
  try {
    await AesGcm.decrypt(ciphertext, key, nonce, aad);
    return true; // Authentic
  } catch (error) {
    return false; // Not authentic
  }
}

// Usage
const isValid = await verifyAuthenticity(ciphertext, key, nonce, aad);

if (isValid) {
  console.log('Data is authentic');
} else {
  console.log('Data has been tampered with');
}

Note: This still performs decryption internally. GCM doesn’t support tag verification without decryption.

Performance

Decryption Speed

Similar to encryption (hardware-accelerated):

With AES-NI: ~2-5 GB/s
Software-only: ~50-200 MB/s

Benchmarks

const key = await AesGcm.generateKey(256);
const plaintext = new Uint8Array(1024 * 1024); // 1 MB
crypto.getRandomValues(plaintext);

// Encrypt once
const nonce = AesGcm.generateNonce();
const ciphertext = await AesGcm.encrypt(plaintext, key, nonce);

// Benchmark decryption
const iterations = 100;
const start = performance.now();

for (let i = 0; i < iterations; i++) {
  await AesGcm.decrypt(ciphertext, key, nonce);
}

const end = performance.now();
const totalMB = (plaintext.length * iterations) / (1024 * 1024);
const seconds = (end - start) / 1000;
const throughput = totalMB / seconds;

console.log(`Decryption throughput: ${throughput.toFixed(2)} MB/s`);

Examples

Wallet Decryption

import * as AesGcm from '@tevm/voltaire/crypto/aesgcm';

async function unlockWallet(encryptedWallet, password) {
  try {
    // Derive key from password
    const salt = new Uint8Array(encryptedWallet.salt);
    const key = await AesGcm.deriveKey(
      password,
      salt,
      encryptedWallet.pbkdf2Iterations,
      256
    );

    // Decrypt private key
    const nonce = new Uint8Array(encryptedWallet.nonce);
    const ciphertext = new Uint8Array(encryptedWallet.ciphertext);
    const privateKey = await AesGcm.decrypt(ciphertext, key, nonce);

    return {
      success: true,
      privateKey
    };
  } catch (error) {
    return {
      success: false,
      error: 'Invalid password or corrupted wallet'
    };
  }
}

// Usage
const result = await unlockWallet(encryptedWallet, userPassword);

if (result.success) {
  console.log('Wallet unlocked');
  // Use result.privateKey
} else {
  console.error(result.error);
}

Database Field Decryption

class EncryptedDatabase {
  constructor(key) {
    this.key = key;
  }

  async decryptField(encrypted) {
    try {
      const nonce = new Uint8Array(encrypted.nonce);
      const ciphertext = new Uint8Array(encrypted.ciphertext);

      const plaintext = await AesGcm.decrypt(ciphertext, this.key, nonce);
      return JSON.parse(new TextDecoder().decode(plaintext));
    } catch (error) {
      console.error('Field decryption failed:', error);
      throw new Error('Data corruption detected');
    }
  }

  async queryDecrypted(query) {
    const rows = await this.db.query(query);

    return await Promise.all(
      rows.map(async (row) => ({
        id: row.id,
        data: await this.decryptField(row.encrypted_data)
      }))
    );
  }
}

// Usage
const db = new EncryptedDatabase(key);
const results = await db.queryDecrypted('SELECT * FROM users');

results.forEach((row) => {
  console.log(`User ${row.id}:`, row.data);
});

Authenticated Message Decryption

async function receiveEncryptedMessage(encrypted, sharedSecret) {
  const key = await AesGcm.importKey(sharedSecret);
  const nonce = new Uint8Array(encrypted.nonce);
  const ciphertext = new Uint8Array(encrypted.ciphertext);
  const aad = new Uint8Array(encrypted.metadata);

  try {
    const plaintext = await AesGcm.decrypt(ciphertext, key, nonce, aad);
    const message = new TextDecoder().decode(plaintext);
    const metadata = JSON.parse(new TextDecoder().decode(aad));

    return {
      success: true,
      message,
      sender: metadata.sender,
      timestamp: metadata.timestamp
    };
  } catch (error) {
    return {
      success: false,
      error: 'Message authentication failed - possible tampering'
    };
  }
}

Common Mistakes

Not Handling Errors

// WRONG: Ignoring errors
const decrypted = await AesGcm.decrypt(ciphertext, key, nonce);
// Could throw and crash

// RIGHT: Handle errors
try {
  const decrypted = await AesGcm.decrypt(ciphertext, key, nonce);
  // Use decrypted data
} catch (error) {
  console.error('Decryption failed:', error);
  // Handle error appropriately
}

Using Wrong Parameters

// WRONG: Using different key
const key1 = await AesGcm.generateKey(256);
const key2 = await AesGcm.generateKey(256);
const ct = await AesGcm.encrypt(pt, key1, nonce);
await AesGcm.decrypt(ct, key2, nonce); // Fails

// WRONG: Using wrong nonce
const nonce1 = AesGcm.generateNonce();
const nonce2 = AesGcm.generateNonce();
const ct = await AesGcm.encrypt(pt, key, nonce1);
await AesGcm.decrypt(ct, key, nonce2); // Fails

// RIGHT: Use same key and nonce
const ct = await AesGcm.encrypt(pt, key, nonce);
const decrypted = await AesGcm.decrypt(ct, key, nonce); // Success

Partial Decryption Assumptions

// WRONG: Assuming partial data on failure
try {
  const decrypted = await AesGcm.decrypt(tamperedCiphertext, key, nonce);
} catch (error) {
  // 'decrypted' is undefined - no partial data available
  // Cannot extract any information from failed decryption
}

Overview

Getting Started

Core Concepts

Skills

JSONRPCProvider

Contract

Primitives

Cryptography

EVM

Utils

Guides

Examples

Swift

Zig

Developer Documentation

Generated API (TypeDoc)

​Overview

​Decryption Operation

​Basic Decryption

​How It Works

​Parameters

​Ciphertext (Required)

​Key (Required)

​Nonce (Required)

​Additional Authenticated Data (Optional)

​Error Handling

​Authentication Failures

​Common Failure Scenarios

​Error Messages

​Security Properties

​Constant-Time Verification

​All-or-Nothing Decryption

​Advanced Usage

​Batch Decryption

​Extract and Decrypt

​Verify Without Decrypting

​Performance

​Decryption Speed

​Benchmarks

​Examples

​Wallet Decryption

​Database Field Decryption

​Authenticated Message Decryption

​Common Mistakes

​Not Handling Errors

​Using Wrong Parameters

​Partial Decryption Assumptions

​References

Overview

Decryption Operation

Basic Decryption

How It Works

Parameters

Ciphertext (Required)

Key (Required)

Nonce (Required)

Additional Authenticated Data (Optional)

Error Handling

Authentication Failures

Common Failure Scenarios

Error Messages

Security Properties

Constant-Time Verification

All-or-Nothing Decryption

Advanced Usage

Batch Decryption

Extract and Decrypt

Verify Without Decrypting

Performance

Decryption Speed

Benchmarks

Examples

Wallet Decryption

Database Field Decryption

Authenticated Message Decryption

Common Mistakes

Not Handling Errors

Using Wrong Parameters

Partial Decryption Assumptions

References