阐述 `check_ajax_referer()` 函数的源码，它是如何验证 AJAX 请求中的 `Nonce`？

Alright, alright, settle down folks! Welcome to my little corner of the internet, where we dissect WordPress functions like a frog in biology class – except, you know, less formaldehyde and more… code. Today’s star is the check_ajax_referer() function. Buckle up, it’s gonna be a fun ride!

The AJAX Nonce: Why We Need It

Imagine a world without security. Actually, don’t. You’re probably living in it already to some extent. But imagine your WordPress site is a wide-open lemonade stand. Anyone can walk up and start messing with things, like changing the price to $100 a glass or swapping out the lemonade for pickle juice.

That’s essentially what can happen with AJAX requests if you don’t have proper security measures. AJAX, being asynchronous, allows scripts to send requests to the server without reloading the page. This is great for user experience, but also makes it vulnerable to Cross-Site Request Forgery (CSRF) attacks.

CSRF is like someone tricking your browser into sending a request to your site without your knowledge. They could, for example, embed a hidden form on another site that automatically submits a request to delete your posts. Nasty stuff!

Enter the Nonce.

A Nonce (Number used ONCE) is a cryptographic token that’s unique and tied to a specific user, action, context, and lifespan. Think of it as a secret handshake that only you and the server know. When your AJAX request includes the correct Nonce, the server knows it’s a legitimate request originating from your site, not some malicious imposter.

Dissecting check_ajax_referer()

The check_ajax_referer() function in WordPress is your trusty bouncer at the AJAX club, ensuring that only the cool kids (legitimate requests) get in. Let’s take a look at how it works.

Basic Usage:

check_ajax_referer( 'my_ajax_action', 'security' );

• 'my_ajax_action': This is the "action" name. It’s a unique identifier for the specific AJAX operation you’re performing. It’s like the password to get into the club.
• 'security': This is the name of the field in your AJAX request that contains the Nonce value. Think of it as the VIP badge.

Under the Hood: Peeking at the Source Code (Simplified)

The actual source code of check_ajax_referer() is relatively straightforward. It basically performs these steps:

1. Retrieves the Nonce: It looks for the Nonce value in the $_REQUEST array (which contains both $_GET and $_POST data) using the field name you provided (e.g., ‘security’).

2. Verifies the Nonce: It then calls the wp_verify_nonce() function to check if the Nonce is valid.

3. Handles Errors (if any): If the Nonce is missing or invalid, it triggers an error, usually by calling wp_die(), which terminates the AJAX request and sends an appropriate error message back to the client.

Here’s a simplified representation of what the function might look like (for illustrative purposes; the actual WordPress core code may have variations):

<?php
/**
 * Verifies the AJAX request to prevent CSRF.
 *
 * @param string $action  Action nonce.
 * @param string $query_arg Optional. Key to check for the nonce in `$_REQUEST`. Default 'security'.
 * @param bool   $die       Optional. Whether to die if the nonce is invalid. Default true.
 * @return bool|int False if the nonce is invalid, 1 if the nonce is valid.
 */
function my_check_ajax_referer( $action = -1, $query_arg = false, $die = true ) {
    $query_arg = $query_arg ? $query_arg : 'security';

    $nonce = '';
    if ( isset( $_REQUEST[ $query_arg ] ) ) {
        $nonce = $_REQUEST[ $query_arg ];
    }

    if ( ! $nonce ) {
        if ( $die ) {
            wp_die( 'Security check failed', 'error', [ 'response' => 403 ] ); // Or a more specific error
        }
        return false;
    }

    $result = wp_verify_nonce( $nonce, $action );

    if ( ! $result ) {
        if ( $die ) {
            wp_die( 'Security check failed', 'error', [ 'response' => 403 ] ); // Or a more specific error
        }
        return false;
    }

    return $result; // 1 if valid, false if invalid
}

Explanation of the Simplified Code:

• $action: The unique identifier for your AJAX action. This is crucial.
• $query_arg: The name of the variable in the $_REQUEST array that holds the Nonce. Defaults to ‘security’ if you don’t specify it.
• $nonce = $_REQUEST[ $query_arg ];: This line retrieves the Nonce value from the $_REQUEST array using the specified $query_arg.
• wp_verify_nonce( $nonce, $action );: This is where the magic happens. This function is the workhorse that actually validates the Nonce. We’ll dive deeper into wp_verify_nonce() shortly.
• wp_die(): If the Nonce is invalid and $die is true (the default), this function halts execution and sends an error message back to the browser. This prevents the AJAX request from proceeding. The [ 'response' => 403 ] part sets the HTTP status code to 403 (Forbidden), indicating that the client doesn’t have permission to perform the action.

The Real Hero: wp_verify_nonce()

The wp_verify_nonce() function is the core of the Nonce validation process. It takes two arguments:

• $nonce: The Nonce value you received from the AJAX request.
• $action: The action name you used when you created the Nonce.

What wp_verify_nonce() Does:

1. Decodes the Nonce: Nonces are often encoded (e.g., with Base64) to make them slightly less obvious. wp_verify_nonce() decodes the Nonce to get the original value.

2. Extracts Information: The Nonce contains information like the timestamp when it was created and the user ID. wp_verify_nonce() extracts this information.

3. Checks Timeliness: Nonces have a limited lifespan (usually 12 hours by default). wp_verify_nonce() checks if the Nonce has expired. If it has, the Nonce is invalid. It does this by comparing the timestamp extracted from the Nonce with the current time. It allows a window before and after the creation time to account for server time discrepancies.

4. Reconstructs the Hash: wp_verify_nonce() reconstructs the expected Nonce value using the same algorithm that was used to create it. This involves using the action name, user ID, and a secret key.

5. Compares the Values: Finally, it compares the reconstructed Nonce value with the Nonce value it received. If they match, the Nonce is valid.

Simplified wp_verify_nonce() (Illustrative):

<?php
/**
 * Verifies that a nonce is valid.
 *
 * The user-specific nonce is valid for 12 hours.
 *
 * @param string|int $nonce Nonce that was used in the form to verify
 * @param string|int $action Action that was used when the nonce was created.
 * @return false|int False if the nonce is invalid, 1 if the nonce is valid.
 */
function my_wp_verify_nonce( $nonce, $action = -1 ) {
    $nonce = (string) $nonce;

    $i = wp_nonce_tick();

    // Nonce generated 0-12 hours ago
    $expected = my_wp_hash( $i . '|' . $action . '|' . get_current_user_id(), 'nonce' );
    if ( my_wp_hash_equals( $expected, $nonce ) ) {
        return 1;
    }

    // Nonce generated 12-24 hours ago
    $expected = my_wp_hash( ( $i - 1 ) . '|' . $action . '|' . get_current_user_id(), 'nonce' );
    if ( my_wp_hash_equals( $expected, $nonce ) ) {
        return 2;
    }

    // Invalid nonce
    return false;
}

/**
 * Returns the time-dependent variable for nonce creation.
 *
 * @return int
 */
function wp_nonce_tick() {
    /**
     * Filter the lifespan of nonces.
     *
     * By default, nonces expire after 12 hours.
     *
     * @since 4.5.0
     *
     * @param int $lifespan Nonce lifespan in seconds.
     */
    $lifespan = apply_filters( 'nonce_life', DAY_IN_SECONDS / 2 );

    return ceil( time() / ( $lifespan ) );
}

/**
 * Hashes the nonce based on the secret key.
 *
 * @param string $data
 * @param string $token
 * @return string
 */
function my_wp_hash( $data, $token = 'auth' ) {
    $key = wp_salt( $token );
    return hash_hmac( 'md5', $data, $key );
}

/**
 * Timing attack safe string comparison
 *
 * Compares two strings using the same amount of time whether they match or not.
 *
 * This prevents cryptographic timing attacks.
 *
 * @since 3.9.2
 *
 * @param string $a First string.
 * @param string $b Second string.
 * @return bool Whether or not the two strings are equal.
 */
function my_wp_hash_equals( $a, $b ) {
    $a_length = strlen( $a );
    $b_length = strlen( $b );

    if ( $a_length !== $b_length ) {
        return false;
    }

    $result = 0;

    for ( $i = 0; $i < $a_length; $i++ ) {
        $result |= ord( $a[ $i ] ) ^ ord( $b[ $i ] );
    }

    return 0 === $result;
}

Key Points about the Simplified wp_verify_nonce() Code:

• wp_nonce_tick(): This function returns a time-based "tick" value that changes every 12 hours (by default, adjustable with the nonce_life filter). This is part of what makes the Nonce expire.

• my_wp_hash(): This function simulates the hashing algorithm used to create the Nonce. It uses a secret key (wp_salt()) to generate a unique hash based on the action, user ID, and the time "tick." The wp_salt() function retrieves the WordPress salt values defined in wp-config.php. These salts are crucial for security and should never be shared.

• my_wp_hash_equals(): This is a crucial security measure. It performs a "timing attack safe" string comparison. Regular string comparison can leak information about the strings being compared based on how long the comparison takes. my_wp_hash_equals() ensures that the comparison takes the same amount of time regardless of whether the strings match or not, preventing attackers from using timing attacks to guess the Nonce.

• Time Window: The code checks for Nonces created within the current 12-hour window and the previous 12-hour window. This allows for some leeway in case of server time discrepancies or caching issues.

Why wp_hash_equals() is Important:

Imagine you’re trying to crack a safe by trying different combinations. If the safe takes longer to reject an incorrect combination that’s close to the correct one, you can use that information to narrow down your search.

Similarly, with string comparison, if the comparison takes longer when the strings are more similar, an attacker could potentially use that information to guess the Nonce. wp_hash_equals() prevents this by ensuring that the comparison time is constant, regardless of the similarity of the strings.

Generating the Nonce: wp_create_nonce()

Okay, so we know how to verify a Nonce, but how do we create one in the first place? That’s where wp_create_nonce() comes in.

Usage:

$nonce = wp_create_nonce( 'my_ajax_action' );

• 'my_ajax_action': The same action name you’ll use when verifying the Nonce.

What wp_create_nonce() Does:

wp_create_nonce() generates a unique, time-limited Nonce value. It uses the same hashing algorithm and secret key as wp_verify_nonce(), ensuring that the Nonce can be successfully validated later.

Simplified wp_create_nonce() (Illustrative):

<?php
/**
 * Creates a cryptographic token to verify an action.
 *
 * @param string|int $action Scalar value to add context to the nonce.
 * @return string The token.
 */
function my_wp_create_nonce( $action = -1 ) {
    $i = wp_nonce_tick();

    return my_wp_hash( $i . '|' . $action . '|' . get_current_user_id(), 'nonce' );
}

Explanation:

• It gets the current time "tick" using wp_nonce_tick().
• It uses the my_wp_hash() function (which uses wp_salt()) to generate a hash based on the tick, the action, and the current user’s ID.
• The resulting hash is the Nonce value.

Putting it All Together: A Complete Example

Here’s a complete example of how to use wp_create_nonce() and check_ajax_referer() in your WordPress code.

1. PHP (Server-Side):

<?php
add_action( 'wp_ajax_my_ajax_action', 'my_ajax_handler' ); // For logged-in users
add_action( 'wp_ajax_nopriv_my_ajax_action', 'my_ajax_handler' ); // For non-logged-in users

function my_ajax_handler() {
    // Verify the Nonce
    check_ajax_referer( 'my_ajax_action', 'security' );

    // Your AJAX logic here
    $data = $_POST['data']; // Example: Get data from the AJAX request

    // Sanitize and process the data
    $sanitized_data = sanitize_text_field( $data );
    $result = 'You sent: ' . $sanitized_data;

    // Send a response back to the client
    wp_send_json_success( $result );

    // Always exit to avoid unexpected output
    wp_die();
}

// Enqueue script with localized data
add_action( 'wp_enqueue_scripts', 'my_enqueue_scripts' );
function my_enqueue_scripts() {
    wp_enqueue_script( 'my-ajax-script', get_stylesheet_directory_uri() . '/js/my-ajax-script.js', array( 'jquery' ), '1.0', true );

    // Localize the script with new data
    $translation_array = array(
        'ajax_url' => admin_url( 'admin-ajax.php' ),
        'security' => wp_create_nonce( 'my_ajax_action' )
    );
    wp_localize_script( 'my-ajax-script', 'MyAjax', $translation_array );
}

2. JavaScript (Client-Side):

// /js/my-ajax-script.js
jQuery(document).ready(function($) {
    $('#my-button').click(function() {
        var dataToSend = $('#my-input').val();

        $.ajax({
            url: MyAjax.ajax_url, // Use the localized AJAX URL
            type: 'POST',
            data: {
                action: 'my_ajax_action', // The AJAX action
                security: MyAjax.security, // The Nonce
                data: dataToSend // Your data
            },
            success: function(response) {
                if (response.success) {
                    $('#my-result').text(response.data); // Display the result
                } else {
                    console.error('AJAX Error:', response);
                    $('#my-result').text('Error: ' + response.data);
                }
            },
            error: function(jqXHR, textStatus, errorThrown) {
                console.error('AJAX Error:', textStatus, errorThrown);
                $('#my-result').text('AJAX Error: ' + textStatus);
            }
        });
    });
});

3. HTML (in your theme’s template):

<input type="text" id="my-input" value="Hello, AJAX!">
<button id="my-button">Send AJAX Request</button>
<div id="my-result"></div>

Explanation:

• PHP:
  • We register the AJAX action using add_action(). wp_ajax_my_ajax_action is for logged-in users, and wp_ajax_nopriv_my_ajax_action is for non-logged-in users.
  • my_ajax_handler() is the function that will be executed when the AJAX request is received.
  • Inside my_ajax_handler(), we call check_ajax_referer() to verify the Nonce.
  • We enqueue a JavaScript file and use wp_localize_script() to pass the AJAX URL and the Nonce value to the JavaScript file. This is the safest way to pass data from PHP to JavaScript in WordPress.
• JavaScript:
  • We use jQuery to handle the button click and send the AJAX request.
  • The data object includes the action (the name of the AJAX action), the security (the Nonce), and any other data you want to send to the server.
  • The success callback handles the response from the server.
• HTML:
  • Simple HTML to create an input field, a button, and a place to display the result.

Important Considerations:

• Action Names: Choose descriptive and unique action names for your AJAX operations. This helps prevent conflicts with other plugins or themes.
• Nonce Lifespan: The default Nonce lifespan of 12 hours is usually sufficient, but you can adjust it using the nonce_life filter if needed. Be careful when shortening the lifespan, as it can lead to unexpected errors if users take longer than expected to complete a task.
• Data Sanitization: Always sanitize and validate any data you receive from the client before using it in your code. This is essential to prevent security vulnerabilities like Cross-Site Scripting (XSS) and SQL injection. Use WordPress functions like sanitize_text_field(), absint(), and esc_url_raw() to sanitize your data.
• Error Handling: Implement proper error handling in both your PHP and JavaScript code. This will help you debug issues and provide a better user experience.
• HTTPS: Always use HTTPS to encrypt the communication between the client and the server. This prevents attackers from intercepting the Nonce and other sensitive data.

Common Mistakes and How to Avoid Them

• Forgetting to Include the Nonce: The most common mistake is simply forgetting to include the Nonce in your AJAX request. Double-check that you’re passing the Nonce value in the data object of your AJAX request.
• Using the Wrong Action Name: Make sure you’re using the same action name when creating and verifying the Nonce. A typo in the action name will cause the Nonce validation to fail.
• Not Sanitizing Data: As mentioned earlier, never trust data that comes from the client. Sanitize and validate all input to prevent security vulnerabilities.
• Hardcoding Salts or Keys: Never hardcode salt values or secret keys in your code. WordPress provides the wp_salt() function to retrieve the salts defined in wp-config.php.
• Incorrectly Using wp_localize_script(): Make sure you’re using wp_localize_script() correctly to pass data from PHP to JavaScript. The first argument is the handle of the script you’re localizing, the second argument is the name of the JavaScript object that will contain the data, and the third argument is an array of data to pass.

Conclusion

The check_ajax_referer() function and the underlying Nonce system are essential security measures for protecting your WordPress site from CSRF attacks. By understanding how these functions work and following best practices, you can ensure that your AJAX requests are secure and that your site remains protected.

So, that’s it for today’s lecture. Go forth and write secure AJAX code! And remember, a little bit of security goes a long way in keeping the bad guys out of your lemonade stand.