sodium_crypto_box encrypts and authenticates a message using the sender secret key and recipient public key, combined in a sender keypair.
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_box encrypts and authenticates a message using the sender secret key and recipient public key, combined in a sender keypair.
The sodium extension must be enabled.
Syntax and Return Value
sodium_crypto_box(string $message, string $nonce, string $key_pair): 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_pair (string) | Use the PHP signature above to determine the exact expected input type; validate untrusted inputs before calling. |
The declared return type is shown above. Errors can include false results or exceptions depending on this API: Keep secret keys private; the nonce must never repeat with the same key pair. A sealed box does not authenticate the sender.
Example 1: Basic Operation
The sender and receiver must use matching public and secret key material, not share private keys.
<?php
$message = "Account update";
$sender = sodium_crypto_box_keypair();
$receiver = sodium_crypto_box_keypair();
$nonce = random_bytes(SODIUM_CRYPTO_BOX_NONCEBYTES);
$senderForReceiver = sodium_crypto_box_keypair_from_secretkey_and_publickey(sodium_crypto_box_secretkey($sender), sodium_crypto_box_publickey($receiver));
$receiverFromSender = sodium_crypto_box_keypair_from_secretkey_and_publickey(sodium_crypto_box_secretkey($receiver), sodium_crypto_box_publickey($sender));
$sealed = sodium_crypto_box($message, $nonce, $senderForReceiver);
echo strlen($sealed) . " bytes";Example 2: A Different Use Case
The sender and receiver must use matching public and secret key material, not share private keys.
<?php
// Check the alternative case.
$message = "New order: 42";
$sender = sodium_crypto_box_keypair();
$receiver = sodium_crypto_box_keypair();
$nonce = random_bytes(SODIUM_CRYPTO_BOX_NONCEBYTES);
$senderForReceiver = sodium_crypto_box_keypair_from_secretkey_and_publickey(sodium_crypto_box_secretkey($sender), sodium_crypto_box_publickey($receiver));
$receiverFromSender = sodium_crypto_box_keypair_from_secretkey_and_publickey(sodium_crypto_box_secretkey($receiver), sodium_crypto_box_publickey($sender));
$sealed = sodium_crypto_box($message, $nonce, $senderForReceiver);
echo strlen($sealed) . " bytes";Practical Example: Checking the Result
The sender and receiver must use matching public and secret key material, not share private keys.
<?php
// Verify the expected behavior before using results.
$message = "Export completed";
$sender = sodium_crypto_box_keypair();
$receiver = sodium_crypto_box_keypair();
$nonce = random_bytes(SODIUM_CRYPTO_BOX_NONCEBYTES);
$senderForReceiver = sodium_crypto_box_keypair_from_secretkey_and_publickey(sodium_crypto_box_secretkey($sender), sodium_crypto_box_publickey($receiver));
$receiverFromSender = sodium_crypto_box_keypair_from_secretkey_and_publickey(sodium_crypto_box_secretkey($receiver), sodium_crypto_box_publickey($sender));
$sealed = sodium_crypto_box($message, $nonce, $senderForReceiver);
echo strlen($sealed) . " bytes";Important Behavior and Edge Cases
Keep secret keys private; the nonce must never repeat with the same key pair. A sealed box does not authenticate the sender.
The sender must use the receiver public key and its own secret key, and the receiver needs a complementary pair. Sealed boxes intentionally do not authenticate the sender.
Comparison with Related Functions
| Approach | Key distinction |
|---|---|
| sodium_crypto_box | sodium_crypto_box encrypts and authenticates a message using the sender secret key and recipient public key, combined in a sender keypair. |
| Related technique | secretbox works with a single shared symmetric key rather than a public/secret key pair. |
Common Beginner Mistakes
| Mistake | Correct approach |
|---|---|
| Confusing this operation with a neighboring cryptographic or security mechanism | secretbox works with a single shared symmetric key rather than a public/secret key pair. |
| Ignoring a security prerequisite or failure case | Keep secret keys private; the nonce must never repeat with the same key pair. A sealed box does not authenticate the sender. |
Key Takeaways
- sodium_crypto_box encrypts and authenticates a message using the sender secret key and recipient public key, combined in a sender keypair.
- Keep secret keys private; the nonce must never repeat with the same key pair. A sealed box does not authenticate the sender.
- secretbox works with a single shared symmetric key rather than a public/secret key pair.
Apply this behavior to a real application only after confirming the required extension, configuration and failure handling on the deployment runtime.