This guide explains how request signatures are generated, how to generate these signatures in a headless system, and how to disable the signature verification if needed. This approach is used to enhance compatibility with caching mechanisms.
What is the Request Signature and Why Use It?
Purpose of the Signature
The request signature is a security measure used to verify the authenticity of incoming requests. It ensures that the request has not been tampered with and is from a trusted source.
Why Use a Signature Instead of a Nonce?
In version 14.9, the decision was made to use signatures instead of nonces to improve compatibility with caching mechanisms. Nonces can be problematic in environments with aggressive caching because they expire quickly and are tied to the session. Signatures, on the other hand, are generated based on a consistent payload and a server-side secret (salt), making them more robust in cached environments.
How the Signature is Generated
Signature Generation Method
The signature is generated using the following method:
md5(wp_salt() . json_encode($payload))
This method combines a WordPress salt with a JSON-encoded string of the payload and generates an MD5 hash. The payload typically includes parameters such as current_page_type and current_page_id.
Example of Signature Generation
Construct the payload using the current_page_type and current_page_id:
$payload = [
$request->get_param('current_page_type'),
(int) $request->get_param('current_page_id'),
];
Generate the signature:
$signature = md5(wp_salt() . json_encode($payload));
This signature is then used to verify the authenticity of the request.
Generating the Signature in a Headless System
Context
If you are working with a headless system (e.g., a React frontend) and not a traditional WordPress theme, you need to ensure that the signature generated on your side matches the one expected by the server.
Steps to Generate the Signature
Construct the Payload: Ensure your payload includes the same parameters (current_page_type and current_page_id).
Generate the Signature: Use the same method to generate the signature on the client side. Here is an example in JavaScript:
const payload = JSON.stringify([current_page_type, current_page_id]);
const signature = md5(wpSalt + payload).toString(); // Generate the MD5 hash
Send the Signature: Include the generated signature with your request.
Disabling Signature Verification
Purpose of the wp_statistics_request_signature_enabled Filter
The wp_statistics_request_signature_enabled filter allows developers to enable or disable the signature verification process for incoming requests. This can be useful for environments where signature verification is not required or for debugging purposes.
Hook Syntax
apply_filters('wp_statistics_request_signature_enabled', true)
Parameters
$enabled (bool): A boolean value that determines whether the signature verification is enabled. The default value is true.
Example Usage
To disable the request signature verification, hook into the wp_statistics_request_signature_enabled filter in your theme or plugin:
add_filter('wp_statistics_request_signature_enabled', 'disable_request_signature');
function disable_request_signature($enabled) {
return false; // Disable signature verification
}
In this example, the filter is set to return false, which disables the signature verification process.
Return Value:
- If the signature is valid or the verification is disabled, the function returns
true.
