In PHP, sodium_crypto_secretstream_xchacha20poly1305_rekey() is useful when your application needs a specific operation rather than manually reproducing it. Rotates an existing secretstream state key while maintaining protocol synchronization. Both sides must rekey at matching points.
Security context: The examples show API usage, not a complete secure messaging protocol. Keep encryption keys secret and use authenticated encryption when integrity is required.
Stream functions work with PHP stream resources, wrappers, contexts or custom filters. Not every wrapper supports every operation.
What Is sodium_crypto_secretstream_xchacha20poly1305_rekey() in PHP?
Rotates an existing secretstream state key while maintaining protocol synchronization. Both sides must rekey at matching points.
Signature:
sodium_crypto_secretstream_xchacha20poly1305_rekey(string $state): voidParameters:
$state— Mutable crypto state returned by the corresponding initialization function.
Return value: void.
Example 1: Basic Usage
This first example shows the method or function in a minimal context. For environment-dependent operations, adapt the required path, stream or connection before running it.
<?php
$key = sodium_crypto_secretstream_xchacha20poly1305_keygen();
[$state, $header] = sodium_crypto_secretstream_xchacha20poly1305_init_push($key);
sodium_crypto_secretstream_xchacha20poly1305_rekey($state);
The important operation is sodium_crypto_secretstream_xchacha20poly1305_rekey(). Rotates an existing secretstream state key while maintaining protocol synchronization.
Example 2: Another Input or Scenario
The next example changes the input or surrounding context to show how the operation behaves in a second situation.
<?php
$key = sodium_crypto_secretstream_xchacha20poly1305_keygen();
[$sender, $header] = sodium_crypto_secretstream_xchacha20poly1305_init_push($key);
$receiver = sodium_crypto_secretstream_xchacha20poly1305_init_pull($header, $key);
sodium_crypto_secretstream_xchacha20poly1305_rekey($sender);
sodium_crypto_secretstream_xchacha20poly1305_rekey($receiver);
$cipher = sodium_crypto_secretstream_xchacha20poly1305_push($sender, "After rekey");
print_r(sodium_crypto_secretstream_xchacha20poly1305_pull($receiver, $cipher));
Compare the inputs and the handling of the return value with the first example. Avoid assuming that filesystem paths, resource states or binary bytes are interchangeable.
Practical Example: Applying the Operation
This example illustrates how the operation fits into a small application workflow. Paths, streams and secrets must be created or provided securely by the calling application.
<?php
$key = sodium_crypto_secretstream_xchacha20poly1305_keygen();
[$sender, $header] = sodium_crypto_secretstream_xchacha20poly1305_init_push($key);
$receiver = sodium_crypto_secretstream_xchacha20poly1305_init_pull($header, $key);
$first = sodium_crypto_secretstream_xchacha20poly1305_push($sender, "Before rekey");
var_dump(sodium_crypto_secretstream_xchacha20poly1305_pull($receiver, $first));
sodium_crypto_secretstream_xchacha20poly1305_rekey($sender);
sodium_crypto_secretstream_xchacha20poly1305_rekey($receiver);
$second = sodium_crypto_secretstream_xchacha20poly1305_push($sender, "After rekey");
var_dump(sodium_crypto_secretstream_xchacha20poly1305_pull($receiver, $second));
Practical note: Rotates an existing secretstream state key while maintaining protocol synchronization. Both sides must rekey at matching points.
Important Behavior and Edge Cases
- Rotates an existing secretstream state key while maintaining protocol synchronization. Both sides must rekey at matching points.
- Check failure values and exceptions; do not assume every environment supports the same stream wrapper, extension or filesystem capability.
- When handling paths, streams or external input, validate inputs before using results and release resources after use.
Comparison With Related Functions
| Function or Method | Behavior |
|---|---|
sodium_crypto_secretstream_xchacha20poly1305_rekey() | uses authenticated chunked encryption with a header and tag. |
sodium_crypto_stream_xchacha20_xor() | uses unauthenticated raw stream encryption. |
Common Beginner Mistakes
| Mistake | Correct Approach |
|---|---|
Assuming sodium_crypto_secretstream_xchacha20poly1305_rekey() can be used without its required setup | Provide the correct file, stream, state, key or object before calling it; Rotates an existing secretstream state key while maintaining protocol synchronization. |
| Forgetting to transmit the secretstream header | Send the public header with the encrypted chunks so the receiver can initialize its decryption state. |
| Changing the chunk order or skipping authentication checks | Process chunks sequentially, check the result of pull(), and finish with the FINAL tag. |
Key Takeaways
sodium_crypto_secretstream_xchacha20poly1305_rekey()rotates an existing secretstream state key while maintaining protocol synchronization. Both sides must rekey at matching points.- Use appropriate input types and verify results before continuing.
- Prefer specialized, safer APIs when the operation concerns untrusted input, encryption or network traffic.
In summary: Rotates an existing secretstream state key while maintaining protocol synchronization. Both sides must rekey at matching points. Build in error handling and use this function where its specific behavior matches the application requirements.