sodium_crypto_secretbox encrypts and authenticates a message using XSalsa20-Poly1305, a secret key and a fresh nonce.
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_secretbox encrypts and authenticates a message using XSalsa20-Poly1305, a secret key and a fresh nonce.
The sodium extension must be enabled.
Syntax and Return Value
sodium_crypto_secretbox(string $message, string $nonce, string $key): string| Parameter | Purpose |
|---|---|
| $message (string) | The plaintext or input message bytes; content is not automatically character-normalized. |
| $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: Use a fresh 24-byte nonce with each encryption under one key; the nonce can be stored alongside the ciphertext.
Example 1: Basic Operation
Never repeat a nonce with the same key. Check for false before using decrypted plaintext.
<?php
$message = "Account update";
$key = sodium_crypto_secretbox_keygen();
$nonce = random_bytes(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);
$ciphertext = sodium_crypto_secretbox($message, $nonce, $key);
echo strlen($ciphertext) . " bytes";Example 2: A Different Use Case
Verify that authenticated decryption recovers exactly the original message.
<?php
// Check the alternative case.
$message = "New order: 42";
$key = sodium_crypto_secretbox_keygen();
$nonce = random_bytes(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);
$ciphertext = sodium_crypto_secretbox($message, $nonce, $key);
var_dump(sodium_crypto_secretbox_open($ciphertext, $nonce, $key) === $message);Practical Example: Checking the Result
Change a ciphertext byte and check that authentication refuses to open it.
<?php
// Verify the expected behavior before using results.
$message = "Export completed";
$key = sodium_crypto_secretbox_keygen();
$nonce = random_bytes(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);
$ciphertext = sodium_crypto_secretbox($message, $nonce, $key);
$ciphertext[0] = chr(ord($ciphertext[0]) ^ 1);
var_dump(sodium_crypto_secretbox_open($ciphertext, $nonce, $key) === false);Important Behavior and Edge Cases
Use a fresh 24-byte nonce with each encryption under one key; the nonce can be stored alongside the ciphertext.
Use a fresh 24-byte nonce with each encryption under one key; the nonce can be stored alongside the ciphertext.
Comparison with Related Functions
| Approach | Key distinction |
|---|---|
| sodium_crypto_secretbox | sodium_crypto_secretbox encrypts and authenticates a message using XSalsa20-Poly1305, a secret key and a fresh nonce. |
| Related technique | AEAD XChaCha20-Poly1305 supports additional authenticated data. |
Common Beginner Mistakes
| Mistake | Correct approach |
|---|---|
| Confusing this operation with a neighboring cryptographic or security mechanism | AEAD XChaCha20-Poly1305 supports additional authenticated data. |
| Ignoring a security prerequisite or failure case | Use a fresh 24-byte nonce with each encryption under one key; the nonce can be stored alongside the ciphertext. |
Key Takeaways
- sodium_crypto_secretbox encrypts and authenticates a message using XSalsa20-Poly1305, a secret key and a fresh nonce.
- Use a fresh 24-byte nonce with each encryption under one key; the nonce can be stored alongside the ciphertext.
- AEAD XChaCha20-Poly1305 supports additional authenticated data.
Apply this behavior to a real application only after confirming the required extension, configuration and failure handling on the deployment runtime.