hash_equals compares two secret-related byte strings with a timing-resistant equality check, provided the inputs are fixed-length.
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: hash_equals compares two secret-related byte strings with a timing-resistant equality check, provided the inputs are fixed-length.
Part of core PHP or a normally bundled standard extension; check your deployment configuration.
Syntax and Return Value
hash_equals(string $known_string, string $user_string): bool| Parameter | Purpose |
|---|---|
| $known_string (string) | Use the PHP signature above to determine the exact expected input type; validate untrusted inputs before calling. |
| $user_string (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: Authenticate with a secret key; hash_equals requires the known trusted value as its first argument and matching lengths are still observable.
Example 1: Basic Operation
Inspect the expected result: do not print secrets or reuse illustrative credentials in production.
<?php
$known = hash_hmac("sha256", "invoice-42", "example-secret");
$received = hash_hmac("sha256", "invoice-42", "example-secret");
var_dump(hash_equals($known, $received));Example 2: A Different Use Case
Inspect the expected result: do not print secrets or reuse illustrative credentials in production.
<?php
// Check the alternative case.
$known = hash_hmac("sha256", "approved-record", "example-secret");
$received = hash_hmac("sha256", "approved-record", "example-secret");
var_dump(hash_equals($known, $received));Practical Example: Checking the Result
Inspect the expected result: do not print secrets or reuse illustrative credentials in production.
<?php
// Verify the expected behavior before using results.
$known = hash_hmac("sha256", "new-session", "example-secret");
$received = hash_hmac("sha256", "new-session", "example-secret");
var_dump(hash_equals($known, $received));Important Behavior and Edge Cases
Authenticate with a secret key; hash_equals requires the known trusted value as its first argument and matching lengths are still observable.
Distinguish digest encoding from secret-key authentication and keep fixed-length expected authentication values for comparisons.
Comparison with Related Functions
| Approach | Key distinction |
|---|---|
| hash_equals | hash_equals compares two secret-related byte strings with a timing-resistant equality check, provided the inputs are fixed-length. |
| Related technique | Use HMAC to calculate a keyed digest, then hash_equals to compare the received and expected digests. |
Common Beginner Mistakes
| Mistake | Correct approach |
|---|---|
| Confusing this operation with a neighboring cryptographic or security mechanism | Use HMAC to calculate a keyed digest, then hash_equals to compare the received and expected digests. |
| Ignoring a security prerequisite or failure case | Authenticate with a secret key; hash_equals requires the known trusted value as its first argument and matching lengths are still observable. |
Key Takeaways
- hash_equals compares two secret-related byte strings with a timing-resistant equality check, provided the inputs are fixed-length.
- Authenticate with a secret key; hash_equals requires the known trusted value as its first argument and matching lengths are still observable.
- Use HMAC to calculate a keyed digest, then hash_equals to compare the received and expected digests.
Apply this behavior to a real application only after confirming the required extension, configuration and failure handling on the deployment runtime.