How does check_ajax_referer() really work?

Question

Smart Wordpress people say that plugin developers should employ a nonce in each AJAX request that is sent from a page back to the wordpress blog (admin-ajax.php).

This is done by (1) generating a nonce on the server side, via

$nonce = wp_create_nonce  ('my-nonce');

...(2) making that nonce available to Javascript code that sends AJAX requests. For example you could do it like this:

function myplg_emit_scriptblock() {
    $nonce = wp_create_nonce('myplg-nonce');
    echo "<script type='text/javascript'>\n" .
        " var WpPlgSettings = {\n" .
        "   ajaxurl : '" . admin_url( 'admin-ajax.php' ) . "',\n" .
        "   nonce : '" . $nonce . "'\n" .
        " };\n" .
        "</script>\n";
}
add_action('wp_print_scripts','myplg_emit_scriptblock');

...and then (3) the javascript ajax logic references that global variable.

    var url = WpPlgSettings.ajaxurl +
        "?action=my-wp-plg-action&" +
        "nonce=" + WpPlgSettings .nonce +
        "docid=" + id;

    $.ajax({type: "GET",
            url: url,
            headers : { "Accept" : 'application/json' },
            dataType: "json",
            cache: false,
            error: function (xhr, textStatus, errorThrown) {
                ...
            },
            success: function (data, textStatus, xhr) {
                ...
            }
           });

...and finally (4) checking the received nonce in the server-side logic.

add_action( 'wp_ajax_nopriv_skydrv-hotlink', 'myplg_handle_ajax_request' );
add_action( 'wp_ajax_skydrv-hotlink', 'myplg_handle_ajax_request' );
function myplg_handle_ajax_request() {
    check_ajax_referer( 'myplg-nonce', 'nonce' );  // <<=-----
    if (isset($_GET['docid'])) {
        $docid = $_GET['docid'];
        $response = myplg_generate_the_response($docid);
        header( "Content-Type: application/json" );
        echo json_encode( $response ) ;
    }
    else {
        $response = array("error" => "you must specify a docid parameter.");
        echo json_encode( $response ) ;
    }

    exit;
}

But how does the check really work?

Answer 1

Revising some AJAX procedures, I came to the same question. And it's a simple matter of checking the function code:

function check_ajax_referer( $action = -1, $query_arg = false, $die = true ) {
    if ( $query_arg )
        $nonce = $_REQUEST[$query_arg];
    else
        $nonce = isset($_REQUEST['_ajax_nonce']) ? $_REQUEST['_ajax_nonce'] : $_REQUEST['_wpnonce'];

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

    if ( $die && false == $result ) {
        if ( defined( 'DOING_AJAX' ) && DOING_AJAX )
            wp_die( -1 );
        else
            die( '-1' );
    }

    do_action('check_ajax_referer', $action, $result);

    return $result;
}

If wp_verify_nonce is false and you haven't sent false in the $die parameter, then it will execute wp_die( -1 );.

---

In your sample code, check_ajax_referer() will break the execution and return -1 to the AJAX call. If you want to handle the error yourself, add the parameter $die and do your stuff with $do_check:

$do_check = check_ajax_referer( 'myplg-nonce', 'nonce', false ); 

---

Note that the proper way to handle AJAX in WordPress is: register, enqueue and localize the JavaScript files using wp_enqueue_scripts instead of wp_print_scripts.
_{See Use wp_enqueue_scripts() not wp_print_styles().}

Check this update in December 2020 from a core contributor ^{h/t: Rafael Atías}:

Apparently we should now use wp_add_inline_script instead of wp_localize_script to expose a global object that needs to be used by your script.