sodium_crypto_secretbox_open checks and opens a sealed, signed or authenticated ciphertext; the result depends on this function family.
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_open checks and opens a sealed, signed or authenticated ciphertext; the result depends on this function family.
The sodium extension must be enabled.
Syntax and Return Value
sodium_crypto_secretbox_open(string $ciphertext, string $nonce, string $key): string|false| Parameter | Purpose |
|---|---|
| $ciphertext (string) | The encrypted bytes, including any authentication information required by the API. |
| $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);
var_dump(sodium_crypto_secretbox_open($ciphertext, $nonce, $key) === $message);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_open | sodium_crypto_secretbox_open checks and opens a sealed, signed or authenticated ciphertext; the result depends on this function family. |
| 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_open checks and opens a sealed, signed or authenticated ciphertext; the result depends on this function family.
- 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.