AES-GCM Encryption for Developers: A Practical Guide

AES-GCM (Advanced Encryption Standard in Galois/Counter Mode) is the gold standard for symmetric encryption. It provides both confidentiality (data is unreadable without the key) and integrity (tampered data is detected and rejected). This combination is called authenticated encryption, and it's what you should use by default.

Why AES-256-GCM?

Older encryption modes like AES-CBC encrypt data but don't detect tampering. An attacker who can't read the data can still modify it — and in some cases, this leads to full decryption via padding oracle attacks. AES-GCM solves this:

How AES-GCM Works

1. Key: A 256-bit (32-byte) secret key. Can be a raw key or derived from a password using PBKDF2.
2. IV (Initialization Vector): A 96-bit (12-byte) random value. Must be unique for every encryption operation with the same key.
3. Plaintext → Ciphertext: AES-GCM encrypts the data using CTR mode internally.
4. Authentication Tag: A 128-bit tag computed over the ciphertext and any additional authenticated data (AAD). The recipient must verify this tag before decrypting.

Encrypting Data

Use the Auth Toolkit API to encrypt with AES-256-GCM:

curl -X POST https://auth.toolkitapi.io/v1/auth/encrypt \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"plaintext": "Sensitive data here", "password": "my-strong-password"}'

{
  "ciphertext": "pMK3Y6MiDSBqQuoVpw==",
  "iv": "bhT5IGCY7Zs617Lr",
  "tag": "FYoo/8bjhLirq8BDgkH7vQ==",
  "algorithm": "AES-256-GCM",
  "key_derived": true,
  "salt": "1W0NCS2rmSYhc1O6wHPJCA=="
}

When you provide a password instead of a raw key, the API derives a 256-bit key using PBKDF2-SHA256 with a random salt. The salt is returned so you can recreate the same key for decryption.

Using a Raw Key

If you manage keys yourself, pass a 256-bit hex key directly:

curl -X POST https://auth.toolkitapi.io/v1/auth/encrypt \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "plaintext": "Sensitive data",
    "key": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
  }'

In this case, key_derived will be false and salt will be null.

Decrypting Data

Pass back the ciphertext, IV, tag, and the same password (or key):

curl -X POST https://auth.toolkitapi.io/v1/auth/decrypt \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ciphertext": "pMK3Y6MiDSBqQuoVpw==",
    "iv": "bhT5IGCY7Zs617Lr",
    "tag": "FYoo/8bjhLirq8BDgkH7vQ==",
    "password": "my-strong-password",
    "salt": "1W0NCS2rmSYhc1O6wHPJCA=="
  }'

{
  "plaintext": "Sensitive data here",
  "algorithm": "AES-256-GCM"
}

If the tag doesn't match — because the ciphertext was modified, the wrong key was used, or the IV was changed — decryption fails with an authentication error. This is the integrity guarantee at work.

Critical Rules

Never reuse an IV with the same key

AES-GCM is catastrophically broken if you encrypt two messages with the same key and IV. The attacker can XOR the ciphertexts to recover both plaintexts and forge authentication tags. Always use a cryptographically random 96-bit IV for every encryption.

Store all four components

To decrypt, you need: ciphertext, IV, tag, and (if password-based) the salt. They're not secret — only the key/password is. Store or transmit them together.

Use 256-bit keys

AES-128 is still secure, but AES-256 provides a safety margin against future advances (including potential quantum computing threats). There's minimal performance difference.

Don't encrypt with the user's password directly

User passwords have low entropy. Always derive a key using PBKDF2, scrypt, or Argon2 with a unique salt and high iteration count. The Auth Toolkit handles this automatically when you use the password parameter.

When to Use AES-GCM

AES-GCM is for reversible encryption — when you need to get the original data back. For passwords, use one-way hashing. For data integrity without secrecy, use HMAC.