Changeset 45565

Timestamp:

06/25/2019 05:06:57 PM (5 years ago)

Author:

johnbillion

Message:

Docs: Correct and improve the docs for a few nonce-related functions.

See #47110

File:

• trunk/src/wp-includes/pluggable.php (modified) (4 diffs)

trunk/src/wp-includes/pluggable.php

@@ -1075 +1075 @@
 if ( ! function_exists( 'check_admin_referer' ) ) :
     /**
-     * Makes sure that a user was referred from another admin page.
-     *
-     * To avoid security exploits.
+     * Ensures intent by verifying that a user was referred from another admin page with the correct security nonce.
+     *
+     * This function ensures the user intends to perform a given action, which helps protect against clickjacking style
+     * attacks. It verifies intent, not authorisation, therefore it does not verify the user's capabilities. This should
+     * be performed with `current_user_can()` or similar.
+     *
+     * If the nonce value is invalid, the function will exit with an "Are You Sure?" style message.
      *
      * @since 1.2.0
-     *
-     * @param int|string $action    Action nonce.
-     * @param string     $query_arg Optional. Key to check for nonce in `$_REQUEST` (since 2.5).
-     *                              Default '_wpnonce'.
+     * @since 2.5.0 The `$query_arg` parameter was added.
+     *
+     * @param int|string $action    The nonce action.
+     * @param string     $query_arg Optional. Key to check for nonce in `$_REQUEST`. Default '_wpnonce'.
      * @return false|int False if the nonce is invalid, 1 if the nonce is valid and generated between
      *                   0-12 hours ago, 2 if the nonce is valid and generated between 12-24 hours ago.
@@ -2019 +2023 @@
 if ( ! function_exists( 'wp_nonce_tick' ) ) :
     /**
-     * Get the time-dependent variable for nonce creation.
+     * Returns the time-dependent variable for nonce creation.
      *
      * A nonce has a lifespan of two ticks. Nonces in their second tick may be
@@ -2044 +2048 @@
 if ( ! function_exists( 'wp_verify_nonce' ) ) :
     /**
-     * Verify that correct nonce was used with time limit.
-     *
-     * The user is given an amount of time to use the token, so therefore, since the
-     * UID and $action remain the same, the independent variable is the time.
+     * Verifies that a correct security nonce was used with time limit.
+     *
+     * A nonce is valid for 24 hours (by default).
      *
      * @since 2.0.3
      *
-     * @param string     $nonce  Nonce that was used in the form to verify
+     * @param string     $nonce  Nonce value that was used for verification, usually via a form field.
      * @param string|int $action Should give context to what is taking place and be the same when nonce was created.
      * @return false|int False if the nonce is invalid, 1 if the nonce is valid and generated between
@@ -2136 +2139 @@
 if ( ! function_exists( 'wp_salt' ) ) :
     /**
-     * Get salt to add to hashes.
+     * Returns a salt to add to hashes.
      *
      * Salts are created using secret keys. Secret keys are located in two places: