Using a nonce (number used once) is the best way to protect your plugin against a cross-site request forgery (CSRF) hacker-attack. Nonces are used on requests (saving options in admin, Ajax requests, performing an action etc) and prevent unauthorized access by providing a secret 'key' and checking it each time the code is used.
Nonces in WordPress
Nonces work in the following way:
- First you generate a nonce with a unique identifier
- You pass the nonce along other query data (link or form) to you script
- You verify the nonce before doing anything else
In order to create a nonce you can use wp_create_nonce() function.
$nonce= wp_create_nonce ('my-nonce');
Next, pass the value of $nonce as a parameter in your request. For example:
<a href="myplugin.php?_wpnonce=<?php echo $nonce ?>">
You can use wp_verify_nonce() function to check the nonce before you perform any other action in the plugin.
$nonce=$_REQUEST['_wpnonce'];
if (! wp_verify_nonce($nonce, 'my-nonce') ) die("Security check");
And that's all! If you thought it can't be any easier than this you'd be wrong.
Using nonce functions
WordPress provides couple of functions to simplify the usage of nonces even more.
For your forms you can use wp_nonce_field() which will output a hidden field with a nonce. Place the function somewhere inside your form. For example:
<form action=... >
<?php wp_nonce_field('my-nonce'); ?>
...
</form>
If you want to add a nonce to a link, you can use wp_nonce_url() function.
For example:
<a href="<?php wp_nonce_url($url, 'my-nonce'); ?>">
If you are using the plugin on administration pages you can then use check_admin_referer() function to check the nonce. For example:
check_admin_referer( 'my-nonce');
It will automatically extract the nonce from query parameters (_wpnonce) and verify it.
Nonce and Ajax scripts
it's easy to use nonce in your Ajax scripts. First create a nonce using wp_create_nonce().
$nonce= wp_create_nonce ('my-nonce');
Then pass the nonce as _ajax_nonce parameter somewhere in your Ajax call:
$("#text").load(".../ajax_response.php?_ajax_nonce=<?php echo $nonce ?>");
To check the nonce in ajax_response.php use check_ajax_referer() function:
check_ajax_referer('my-nonce');
Here is another example (taken from Live Blogroll) plugin:
$nonce = wp_create_nonce( 'wp-live-blogroll' );
...
jQuery.ajax({
type: "GET",
url: '<?php echo $wp_live_blogroll_plugin_url ?>/wp-live-blogroll-ajax.php',
timeout: 3000,
data: {
link_url: this.href,
_ajax_nonce: '<?php echo $nonce ?>'
},
success: function(msg) {
jQuery('#lb_popup').html(msg);
jQuery('#lb_popup').fadeIn(300);
},
error: function(msg) {
jQuery('#lb_popup').html('Error: ' + msg.responseText);
}
})
Receiving file:
function WPLiveRoll_HandleAjax($link_url)
{
// check security
check_ajax_referer( "wp-live-blogroll" );
Including nonces should not take more than 5 minutes for most plugins, and it is something all plugin authors (including me!) should work on.
Continue reading:
- Best practice for adding JavaScript code to WordPress plugins
- 5 cool WordPress plugins you never heard about
- Adding boxes to WordPress 2.5+ Write Post panel
Posted in: WordPress
TAGS:form nonce, form post forgery nonces, javascript http post nonce, live blogroll plugins, nonce key wordpress, url security, using nonce, wordpress ajax security, wordpress api, wordpress developer, wordpress nonce, wordpress nonce ajax, wordpress nonce outside admin, wordpress page security, wordpress security, wordpress url security, wordpress _wpnonce
Hi! My name is Vladimir Prelovac. I am a computer engineer by profession and an adventurer by state of mind.
8 Comments
I've implemented nonces for the Admin pages of my plugin, but after thinking about this for a while I'm of the opinion that its really not an adequate solution. Specifically, there are two short comings with this whole approach:
1. Its NOT a number used once. Its a number that can be used as many times as you want in 24 hours. Does this make a difference? Yes! The whole problem thats trying to be solved is someone hijacking a session (originally, this was just the cookie, but now its the nonce as well). A 24hr window of opportunity is ridiculous. A competent hacker would need about 2minutes in your Wordpress installation (if they were organized) to setup a back door: probably less if they had rehearsed it. Hence my biggest gripe with this types of solutions: a false sense of security. Nonces only marginally increase your protection, but if you read the way people rave about this principle you would think that all threats have been eliminated.
2. Its intrusive. Its a royal pain in the a$$ to mutilate your URLs with this stuff - and even worse when it doesn't provide effective security. At least cookies are transparent to URLs! I can't count the number of times clients of mine have said "our theme doesn't use widgets so we want to embed your plugin-generated URLs directly in our theme". Sounds like a reasonable request. But wait! I need to tell them that those URLs contains nonces and hence you need to fetch them a-new everytime you want to display them. In effect, they're dynamic URLs. That requires them to write PHP code; and over 50% of my clients aren't PHP programmers. My point is that this approach takes away some existing flexibility but doesn't really improve the security of the system in return.
Now that I've got that out, I'm going to propose an alternative, just so I won't be accused of being a whiner.
Go back to the threat and work within the existing constraints.
The threat is session hijacking. Existing constraints are static URLs. Proposals:
1. augment session authentication (i.e. cookies) with IP address filtering. Have Wordpress not only require a valid cookie but a cookie that came from the same IP address it was issued to and was received from. I know IP addresses can be spoofed but nonce sessions can be spoofed too with far greater ease. At least with this approach you don't have to mangle your URLs.
2. Update the cookie value on every request. Although this sounds good in theory, in practice it would probably cause a lot of false-positive lock-outs which would require the user to log back in again. And fundamentally, it actually doesn't resolve the problem: its just reduces the window of opportunity to an incredibly short time. If a hacker were fast enough (i.e. submitted the next page as you before you did) then they would be let in and you would be locked out.
As you can see, it appears that there might not be an effective solution at this level. It may simply be that Wordpress does the best it can (using cookies and source IP address) and leave it up to other technologies to provide a comprehensive security solution: e.g. SSL to stop anyone else from eavesdropping on the data sent back and forth. Perhaps even having Wordpress run its admin functions on a restricted IP port which requires SSL client side authentication to establish the HTTPS connection. At some point you need to ask yourself, what is the value of the website (asset) I'm protecting? what is the likely investment a typical hacker will make to gain control of that asset?, and is my security system's cost inline with these values?
How do you propose the hacker would hijack a session that uses nonces?
Someone had to point out that for us UK readers "nonce" is an extremely widely used and understood slang for a paedophile, which makes virtually every statement above extremely "humorous". Sorry to be childish, but I assure you it's true. http://www.google.es/search?hl=en&rlz=1B3GGGL_en-GBES329ES329&q=nonce+uk&btnG=Search
Well luckily it wasn't me who came up with the expression :)
Thanks a lot for this!
Exactly what I was looking for! Thanks.
thanks, it's just what i'm looking for.
Does this still reign true for Wordpress 2.7 and above?