Changeset 45565

Timestamp:

06/25/2019 05:06:57 PM (7 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: