Skip to content

Commit 7516662

Browse files
committed
Security: Improve Secrets API tests and inline documentation.
Brings the Secrets API tests in line with the PHPUnit test-writing guidelines and tidies the inline documentation. Documentation: * Remove references to the feature plugin, its proposal and its decision records, including in the `_doing_it_wrong()` notice for unnamespaced names. * Add `@global` annotations for the drop-in globals, rewrite the Site Health test summaries as statements, and correct the `WP_Secret::__debugInfo()` description, which also applies to `print_r()`. * Use `/* */` for multi-line comments, "ID" rather than "id", and `@subpackage Secrets` in the test files. Tests: * Add `@ticket 66187` to each test class, a summary and `@covers` annotation to each test, and order annotations consistently. * Move `@covers` targets in the conformance suites from the interfaces to the implementations under test, declared on the concrete test classes, so coverage is attributed to the code that runs. The base suites no longer filter coverage for extending classes. * Add a unique failure message to every assertion within each test, including a new `$message` parameter for `assertRecordSlotDecryptsTo()`. * Assert the result of every setup write. This exposed two separate-process tests that passed without testing anything because no usable key was available; both now define a test key and check the specific error returned. * Remove duplicated tests, rename tests whose names did not match what they check, and name single-use data providers after their test. * Add tests for a store that cannot list its secrets, for every `WP_SECRETS_ERROR_*` constant being pinned, and for a valid but different `WP_SECRETS_KEY`. * Strengthen assertions that could pass without checking their stated behavior, such as missing error codes, counts and the salt-derived key. * Use the `ms-required` and `multisite` groups with `skipWithoutMultisite()` for multisite-only tests, and `skipWithMultisite()` for the `ms-excluded` test, instead of skipping with `markTestSkipped()`. Developed in #15481. Follow-up to r64337, r64344, r64345, r64674. See #66187, #66353. git-svn-id: https://develop.svn.wordpress.org/trunk@65272 602fd350-edb4-49c9-b593-d223f7449a82
1 parent 89c71c8 commit 7516662

38 files changed

Lines changed: 2481 additions & 1048 deletions

‎src/wp-admin/includes/class-wp-site-health.php‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,6 @@
77
* @since 5.2.0
88
*/
99

10-
1110
require_once __DIR__ . '/secrets-site-health.php';
1211

1312
#[AllowDynamicProperties]

‎src/wp-admin/includes/secrets-site-health.php‎

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -10,9 +10,8 @@
1010
/**
1111
* Registers the Secrets API's Site Health tests.
1212
*
13-
* No settings screen – the proposal defers that to 7.3 – but the health signal an
14-
* operator needs to notice a broken key, a weak key source, or a pending rotation is
15-
* in scope now.
13+
* There is no settings screen for secrets, so these tests are how an operator
14+
* notices a broken key, a weak key source, or a pending rotation.
1615
*
1716
* @since 7.2.0
1817
*
@@ -74,7 +73,7 @@ function wp_secrets_site_health_result( string $test, string $label, string $sta
7473
}
7574

7675
/**
77-
* Site Health test: is the site key a dedicated constant, or a weaker fallback?
76+
* Tests whether the site key comes from a dedicated constant or a weaker fallback.
7877
*
7978
* @since 7.2.0
8079
*
@@ -130,7 +129,7 @@ function wp_secrets_site_health_test_key_source(): array {
130129
}
131130

132131
/**
133-
* Site Health test: does every stored secret still decrypt?
132+
* Tests whether every stored secret still decrypts.
134133
*
135134
* Network secrets are included only for a super admin on a multisite install –
136135
* never shown to a site administrator who is not one.
@@ -218,7 +217,7 @@ function wp_secrets_site_health_find_undecryptable( bool $network ): array {
218217
}
219218

220219
/**
221-
* Site Health test: are any secrets flagged as needing rotation?
220+
* Tests whether any secrets are flagged as needing rotation.
222221
*
223222
* @since 7.2.0
224223
*

‎src/wp-includes/load.php‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -849,6 +849,12 @@ function wp_using_ext_object_cache( $using = null ) {
849849
*
850850
* @since 7.2.0
851851
* @access private
852+
*
853+
* @global bool $wp_secrets_dropin_loaded Whether a secrets.php drop-in file was found.
854+
* @global bool $wp_secrets_dropin_broken Whether the drop-in failed to load or left an invalid override.
855+
* @global WP_Secrets_Provider $wp_secrets_provider Optional. Provider override set by the drop-in.
856+
* @global WP_Secrets_Store $wp_secrets_store Optional. Store override set by the drop-in.
857+
* @global WP_Secrets_Keyring $wp_secrets_keyring Optional. Keyring override set by the drop-in.
852858
*/
853859
function wp_load_secrets_dropin(): void {
854860
static $loaded = false;

‎src/wp-includes/secrets.php‎

Lines changed: 37 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@
5050
/**
5151
* A caller passed an argument this API cannot act on.
5252
*
53-
* An unrecognized version constant, or an invalid scope, slot, or site id.
53+
* An unrecognized version constant, or an invalid scope, slot, or site ID.
5454
*
5555
* Distinct from the codes above in cause rather than in severity: those describe
5656
* a runtime condition a correct caller can still hit (a name that failed
@@ -86,9 +86,9 @@
8686
*
8787
* Distinct from WP_SECRETS_ERROR_RECORD_MALFORMED so that an operator, or Site
8888
* Health, can tell a corrupt record apart from one written by a newer version of
89-
* this plugin than is currently active. See
90-
* docs/decisions/0006-record-format-v2-not-read-compatible.md. The upgrade path for a future v2 is not
91-
* designed, so an unrecognized version is rejected outright rather than guessed at.
89+
* WordPress than is currently running. The upgrade path for a future record format
90+
* is not designed, so an unrecognized version is rejected outright rather than
91+
* guessed at.
9292
*
9393
* @since 7.2.0
9494
*/
@@ -184,15 +184,19 @@ function wp_secrets_memzero( &$value ): void {
184184
$alias =& $value;
185185
sodium_memzero( $alias );
186186
} catch ( \Throwable $e ) {
187-
// A value this function doesn't exclusively own (a shared,
188-
// copy-on-write buffer) can legitimately refuse. The unconditional
189-
// reassignment below still runs regardless of what happened here.
187+
/*
188+
* A value this function doesn't exclusively own (a shared,
189+
* copy-on-write buffer) can legitimately refuse. The unconditional
190+
* reassignment below still runs regardless of what happened here.
191+
*/
190192
unset( $e );
191193
}
192194
}
193195

194-
// Reached on every path, including sodium_memzero() success (it leaves the
195-
// variable null, not an empty string) so callers see one consistent contract.
196+
/*
197+
* Reached on every path, including sodium_memzero() success (it leaves the
198+
* variable null, not an empty string) so callers see one consistent contract.
199+
*/
196200
$value = '';
197201
}
198202

@@ -208,9 +212,9 @@ function wp_secrets_memzero( &$value ): void {
208212
* plugin that can run PHP can read any secret, namespaced or not.
209213
*
210214
* An unnamespaced name ('secret-name', no '/') is accepted, but reports through
211-
* _doing_it_wrong(). It exists for one reason: code written against the earlier
212-
* prototype used a flat keyspace, and refusing those names outright would mean
213-
* every such call site has to be rewritten before it can be ported at all.
215+
* _doing_it_wrong(). It exists for one reason: existing code may already use a flat
216+
* keyspace, and refusing those names outright would mean every such call site has
217+
* to be rewritten before it can be ported at all.
214218
* Accepting them keeps that migration incremental. Nothing else should use one.
215219
* Two plugins that both choose 'api-key' collide silently, which is a real problem
216220
* even though it is not a security one.
@@ -268,7 +272,7 @@ function wp_secrets_validate_name( string $name ) {
268272
__FUNCTION__,
269273
sprintf(
270274
/* translators: %s: The unnamespaced secret name. */
271-
__( 'The secret name "%s" has no namespace. Namespaced names ("plugin-slug/secret-name") group secrets by owner so that listings and admin screens can be organized; unnamespaced names are supported only so that code written against the Displace prototype can be ported incrementally.' ),
275+
__( 'The secret name "%s" has no namespace. Namespaced names ("plugin-slug/secret-name") group secrets by owner so that listings and admin screens can be organized; unnamespaced names are supported only so that existing code using flat names can be ported incrementally.' ),
272276
$name
273277
),
274278
'7.2.0'
@@ -301,10 +305,10 @@ function wp_secrets_validate_name( string $name ) {
301305
/**
302306
* Returns the active secret store.
303307
*
304-
* No filter is applied here, or anywhere on the retrieval path. See
305-
* docs/spec/extension-points.md. A secrets.php drop-in overrides the store by setting
306-
* $GLOBALS['wp_secrets_store'] to an instance before this is first called, and
307-
* that global is checked here directly, not through a hook.
308+
* No filter is applied here, or anywhere on the retrieval path. A secrets.php
309+
* drop-in overrides the store by setting $GLOBALS['wp_secrets_store'] to an
310+
* instance before this is first called, and that global is checked here directly,
311+
* not through a hook.
308312
*
309313
* If the global was set but is not a valid WP_Secrets_Store, or if the drop-in
310314
* itself failed to load cleanly, this returns WP_Secrets_Broken_Store rather than
@@ -314,6 +318,9 @@ function wp_secrets_validate_name( string $name ) {
314318
*
315319
* @since 7.2.0
316320
*
321+
* @global bool $wp_secrets_dropin_broken Whether the secrets.php drop-in failed to load cleanly.
322+
* @global WP_Secrets_Store $wp_secrets_store Optional. Store override set by the drop-in.
323+
*
317324
* @return WP_Secrets_Store
318325
*/
319326
function _wp_secrets_get_store(): WP_Secrets_Store {
@@ -350,6 +357,9 @@ function _wp_secrets_get_store(): WP_Secrets_Store {
350357
*
351358
* @since 7.2.0
352359
*
360+
* @global bool $wp_secrets_dropin_broken Whether the secrets.php drop-in failed to load cleanly.
361+
* @global WP_Secrets_Keyring $wp_secrets_keyring Optional. Keyring override set by the drop-in.
362+
*
353363
* @return WP_Secrets_Key_Manager
354364
*/
355365
function _wp_secrets_get_key_manager(): WP_Secrets_Key_Manager {
@@ -385,30 +395,14 @@ function _wp_secrets_get_key_manager(): WP_Secrets_Key_Manager {
385395
*
386396
* @since 7.2.0
387397
*
398+
* @global bool $wp_secrets_dropin_loaded Whether a secrets.php drop-in file was found.
399+
*
388400
* @return bool
389401
*/
390402
function wp_using_secrets_dropin(): bool {
391403
return ! empty( $GLOBALS['wp_secrets_dropin_loaded'] );
392404
}
393405

394-
395-
396-
397-
398-
399-
400-
401-
402-
403-
404-
405-
406-
407-
408-
409-
410-
411-
412406
/**
413407
* Encrypts and stores a secret.
414408
*
@@ -430,10 +424,9 @@ function wp_set_secret( string $name, $value ) {
430424
/**
431425
* Imports an existing option's value as a secret.
432426
*
433-
* For an explicit migration, "on their own explicit upgrade schedule,"
434-
* in the proposal's words, because "core cannot reliably tell which options are
435-
* credentials, and guessing would break sites." The source option is left
436-
* untouched: this reads it, it does not move or delete it.
427+
* For an explicit migration on the caller's own schedule, because core cannot
428+
* reliably tell which options are credentials, and guessing would break sites. The
429+
* source option is left untouched: this reads it, it does not move or delete it.
437430
*
438431
* The imported secret is flagged needs_rotation, unconditionally. A credential that
439432
* sat in a plain option has already been through however many backups and
@@ -474,8 +467,6 @@ function wp_import_option_as_secret( string $option, string $name ) {
474467
return _wp_secrets_set( $name, $value, false, true, 'imported' );
475468
}
476469

477-
478-
479470
/**
480471
* Retrieves a secret.
481472
*
@@ -514,8 +505,6 @@ function wp_delete_secret( string $name ) {
514505
* that has never been rotated, or that does not exist, is a successful no-op:
515506
* the previous slot is already absent either way.
516507
*
517-
* Beyond the API surface the proposal names.
518-
*
519508
* @since 7.2.0
520509
*
521510
* @param string $name The secret's namespaced name.
@@ -528,10 +517,6 @@ function wp_retire_secret_version( string $name ) {
528517
/**
529518
* Lists secrets by name and metadata. Never a value.
530519
*
531-
* Beyond the API surface the proposal names, and justified by its statement that
532-
* the hooks and accessors a future admin screen needs are in scope now, even though
533-
* the screen itself is not.
534-
*
535520
* @since 7.2.0
536521
*
537522
* @param string $namespace Only secrets whose name starts with "{$namespace}/" are
@@ -542,7 +527,7 @@ function wp_retire_secret_version( string $name ) {
542527
*
543528
* @phpstan-return list<array{name: string, fingerprint: string, created: int, has_previous: bool, needs_rotation: bool}>|WP_Error
544529
*/
545-
function wp_list_secrets( string $namespace = '' ) { // phpcs:ignore Universal.NamingConventions.NoReservedKeywordParameterNames.namespaceFound -- $namespace is the parameter name the proposal specifies.
530+
function wp_list_secrets( string $namespace = '' ) { // phpcs:ignore Universal.NamingConventions.NoReservedKeywordParameterNames.namespaceFound -- $namespace is the public parameter name; renaming it would break named-argument callers.
546531
return _wp_secrets_list( $namespace, false );
547532
}
548533

@@ -551,8 +536,7 @@ function wp_list_secrets( string $namespace = '' ) { // phpcs:ignore Universal.N
551536
*
552537
* Site secrets and network secrets are separate functions with separate
553538
* capabilities and separate storage prefixes, with no implicit fallback from one
554-
* scope to the other. The proposal describes network scope but does not name these
555-
* functions; these are this implementation's names for them.
539+
* scope to the other.
556540
*
557541
* @since 7.2.0
558542
*
@@ -641,6 +625,9 @@ function wp_list_network_secrets( string $namespace = '' ) { // phpcs:ignore Uni
641625
*
642626
* @since 7.2.0
643627
*
628+
* @global bool $wp_secrets_dropin_broken Whether the secrets.php drop-in failed to load cleanly.
629+
* @global WP_Secrets_Provider $wp_secrets_provider Optional. Provider override set by the drop-in.
630+
*
644631
* @return WP_Secrets_Provider
645632
*/
646633
function _wp_secrets_get_provider(): WP_Secrets_Provider {

‎src/wp-includes/secrets/class-wp-secret.php‎

Lines changed: 7 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ final class WP_Secret implements JsonSerializable {
3131
* Deliberately not an SplObjectStorage keyed by the instance itself: that holds a
3232
* strong reference to its keys, which would keep every WP_Secret ever constructed
3333
* alive – and its plaintext un-zeroed – for the life of the request. Keying by
34-
* the integer id instead leaves an instance's own reference count to govern its
34+
* the integer ID instead leaves an instance's own reference count to govern its
3535
* lifetime normally, so __destruct() fires and zeroes the value the moment nothing
3636
* else references the instance.
3737
*
@@ -224,13 +224,12 @@ public function __toString(): string {
224224
}
225225

226226
/**
227-
* Masks the instance for var_dump().
227+
* Masks the instance for var_dump() and print_r().
228228
*
229-
* Note that print_r() and var_export() have no equivalent hook. They are safe
230-
* regardless, because the plaintext is never a declared property for them to
231-
* enumerate; they will surface the (non-sensitive) name and fingerprint rather
232-
* than this placeholder. See docs/journal/open-questions.md for the documented
233-
* var_export() limitation.
229+
* Note that var_export() does not use this hook. It does not expose plaintext
230+
* from the vault, but it enumerates all instance properties, including the
231+
* unmasked WP_Error reason on a withheld secret. Use a masked output path
232+
* instead when the reason must remain private.
234233
*
235234
* @since 7.2.0
236235
*
@@ -314,7 +313,7 @@ public function __unserialize( array $data ): void {
314313
* Refuses cloning outright.
315314
*
316315
* A clone would be a second, unaudited reference to the same plaintext with an
317-
* independent lifetime – and, since the vault is keyed by object id rather than
316+
* independent lifetime – and, since the vault is keyed by object ID rather than
318317
* copied, a bare `clone` would otherwise leave the clone's reveal() silently
319318
* reading nothing.
320319
*

‎src/wp-includes/secrets/class-wp-secrets-broken-store.php‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -75,7 +75,6 @@ public function list_names( bool $network = false ): WP_Error {
7575
return $this->error();
7676
}
7777

78-
7978
/**
8079
* Builds the error every method returns.
8180
*

‎src/wp-includes/secrets/class-wp-secrets-cipher.php‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -256,7 +256,7 @@ public function fingerprint( string $master_key, $plaintext ) {
256256
*
257257
* @param string $purpose One of the AAD_* class constants.
258258
* @param string $scope 'site' or 'network'.
259-
* @param int $site_id Blog id for site scope, 0 for network scope.
259+
* @param int $site_id Blog ID for site scope, 0 for network scope.
260260
* @param string $name Validated secret name.
261261
* @param string $slot A WP_Secret_Version constant.
262262
* @return string
@@ -284,7 +284,7 @@ private function build_aad( string $purpose, string $scope, int $site_id, string
284284
*
285285
* @param string $master_key Candidate master key.
286286
* @param string $scope Candidate scope.
287-
* @param int $site_id Candidate site id.
287+
* @param int $site_id Candidate site ID.
288288
* @param string $name Candidate secret name.
289289
* @param string $slot Candidate slot.
290290
* @return true|WP_Error

‎src/wp-includes/secrets/class-wp-secrets-key-manager.php‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@
2222
* - Site scope, blog N: sodium_crypto_kdf_derive_from_key( 32, N, 'wpsecsit', $root ).
2323
* Distinct per blog, which shared network-wide salts otherwise cannot provide.
2424
* - Network scope: sodium_crypto_kdf_derive_from_key( 32, 0, 'wpsecnet', $root ).
25-
* Subkey id 0 is reserved for this (blog ids start at 1) and the context string
25+
* Subkey ID 0 is reserved for this (blog IDs start at 1) and the context string
2626
* differs from the site path, so there is no collision between the two. Identical
2727
* on every blog, so a network secret written on one blog reads on every other.
2828
*
@@ -66,9 +66,9 @@ final class WP_Secrets_Key_Manager {
6666
const NETWORK_KDF_CONTEXT = 'wpsecnet';
6767

6868
/**
69-
* Reserved KDF subkey id for network scope.
69+
* Reserved KDF subkey ID for network scope.
7070
*
71-
* Blog ids start at 1, so this can never collide with a site-scope subkey id.
71+
* Blog IDs start at 1, so this can never collide with a site-scope subkey ID.
7272
*
7373
* @since 7.2.0
7474
* @var int
@@ -136,11 +136,11 @@ public function get_keyring(): WP_Secrets_Keyring {
136136
* @since 7.2.0
137137
*
138138
* @param string $scope 'site' or 'network'.
139-
* @param int|null $site_id Blog id for site scope. Defaults to the current blog.
139+
* @param int|null $site_id Blog ID for site scope. Defaults to the current blog.
140140
* Ignored for network scope.
141141
* @return string|WP_Error 32-byte master key on success. WP_Error on failure,
142142
* including when a caller passes an invalid scope or
143-
* site id – see WP_Secrets_Cipher::validate_common()
143+
* site ID – see WP_Secrets_Cipher::validate_common()
144144
* for why that is a WP_Error and not an exception.
145145
*
146146
* @phpstan-param 'site'|'network' $scope

0 commit comments

Comments
 (0)