sodium_crypto_aead_aes256gcm_encrypt encrypts plaintext and appends an authentication tag.
The examples explain the data format, expected results and the difference between this API and nearby cryptographic operations.
What It Does
The operation is intended for: sodium_crypto_aead_aes256gcm_encrypt encrypts plaintext and appends an authentication tag.
The sodium extension must be enabled.
Syntax and Return Value
sodium_crypto_aead_aes256gcm_encrypt(string $message, string $additional_data, string $nonce, string $key): string| Parameter | Purpose |
|---|---|
| $message (string) | The plaintext or input message bytes; content is not automatically character-normalized. |
| $additional_data (string) | Additional authenticated bytes; these must match on decryption and are not encrypted. |
| $nonce (string) | A fixed-length per-message nonce; the uniqueness rule is essential to security. |
| $key (string) | Raw key bytes in the required algorithm-specific length; protect them from disclosure. |
The declared return type is shown above. Errors can include false results or exceptions depending on this API: Never reuse a nonce with the same key; additional authenticated data is checked but not encrypted. Modified ciphertext fails authentication.
Example 1: Basic Operation
Encrypt or decrypt with a fresh nonce and keep the associated data identical on both sides.
<?php
if (!sodium_crypto_aead_aes256gcm_is_available()) { echo 'AES-GCM unavailable'; } else {
$message = "Account update";
$key = sodium_crypto_aead_aes256gcm_keygen();
$nonce = random_bytes(SODIUM_CRYPTO_AEAD_AES256GCM_NPUBBYTES);
$aad = "order:42";
$ciphertext = sodium_crypto_aead_aes256gcm_encrypt($message, $aad, $nonce, $key);
echo strlen($ciphertext) > strlen($message) ? "ciphertext with tag" : "unexpected output";
}Example 2: A Different Use Case
Validate the ciphertext using decryption or reject an incorrect associated-data value.
<?php
// Check the alternative case.
if (!sodium_crypto_aead_aes256gcm_is_available()) { echo 'AES-GCM unavailable'; } else {
$message = "New order: 42";
$key = sodium_crypto_aead_aes256gcm_keygen();
$nonce = random_bytes(SODIUM_CRYPTO_AEAD_AES256GCM_NPUBBYTES);
$aad = "order:42";
$ciphertext = sodium_crypto_aead_aes256gcm_encrypt($message, $aad, $nonce, $key);
$restored = sodium_crypto_aead_aes256gcm_decrypt($ciphertext, $aad, $nonce, $key);
var_dump($restored === $message);
}Practical Example: Checking the Result
Demonstrate that ciphertext tampering fails authentication rather than returning unsafe plaintext.
<?php
// Verify the expected behavior before using results.
if (!sodium_crypto_aead_aes256gcm_is_available()) { echo 'AES-GCM unavailable'; } else {
$message = "Export completed";
$key = sodium_crypto_aead_aes256gcm_keygen();
$nonce = random_bytes(SODIUM_CRYPTO_AEAD_AES256GCM_NPUBBYTES);
$aad = "order:42";
$ciphertext = sodium_crypto_aead_aes256gcm_encrypt($message, $aad, $nonce, $key);
$ciphertext[0] = chr(ord($ciphertext[0]) ^ 1);
var_dump(sodium_crypto_aead_aes256gcm_decrypt($ciphertext, $aad, $nonce, $key) === false);
}Important Behavior and Edge Cases
Never reuse a nonce with the same key; additional authenticated data is checked but not encrypted. Modified ciphertext fails authentication.
Changing even one ciphertext, nonce or associated-data byte should cause authentication to fail. Store or transmit the nonce alongside ciphertext without reusing it for this key.
Comparison with Related Functions
| Approach | Key distinction |
|---|---|
| sodium_crypto_aead_aes256gcm_encrypt | sodium_crypto_aead_aes256gcm_encrypt encrypts plaintext and appends an authentication tag. |
| Related technique | secretbox authenticates ciphertext but does not accept additional authenticated data. |
Common Beginner Mistakes
| Mistake | Correct approach |
|---|---|
| Confusing this operation with a neighboring cryptographic or security mechanism | secretbox authenticates ciphertext but does not accept additional authenticated data. |
| Ignoring a security prerequisite or failure case | Never reuse a nonce with the same key; additional authenticated data is checked but not encrypted. Modified ciphertext fails authentication. |
Key Takeaways
- sodium_crypto_aead_aes256gcm_encrypt encrypts plaintext and appends an authentication tag.
- Never reuse a nonce with the same key; additional authenticated data is checked but not encrypted. Modified ciphertext fails authentication.
- secretbox authenticates ciphertext but does not accept additional authenticated data.
Apply this behavior to a real application only after confirming the required extension, configuration and failure handling on the deployment runtime.