Tech news / read across sources

Bytewire

Home / Software & Apps

WordPress 7.2 adds a Secrets API, and existing sites will need a new line in wp-config.php

The 7.2 dev note for the Secrets API sets out an encrypted store for API keys, a required WP_SECRETS_KEY and a fight in the comments. What site owners and plugin authors should do.

Section
Software & Apps
Published
Read
5 min
Sources
3
Photo: Estormiz, CC0, via Wikimedia Commons / Wikimedia Commons, CC0

Every plugin that talks to a payment processor or a mail service has to keep an API key somewhere, and a leaked database copy is only as safe as the weakest place those keys were put. WordPress 7.2, scheduled for December 8 according to the release schedule, adds a core API that stores such credentials encrypted. The developer note by Eric Mann, published November 11 and corrected on November 13, explains how it works and what it asks of site owners.

What site owners have to do

Define WP_SECRETS_KEY in wp-config.php. New installs will get it alongside the salts. Existing sites must add it, and according to the note Site Health generates the line to copy. The key should be 32 random bytes, base64-encoded; the note says the API rejects empty values, the sample placeholder and values copied from your auth keys or salts.

Two warnings from the dev note deserve underlining:

  • Without a usable key, reads and writes of stored secrets fail with a secret_key_unavailable error.
  • Change or remove the key after secrets are stored and they become unreadable until you restore the old value.

So treat the key like a database password: back it up outside the site, and do not regenerate it on a whim. Three new Site Health tests under Security flag a missing or unusable key, secrets that cannot be decrypted, and credentials pending rotation.

How it works

Per the note, secrets are encrypted with libsodium’s XChaCha20-Poly1305. Each secret key derives from a random root key, which is itself stored encrypted under WP_SECRETS_KEY, and the data lives in the options tables. One previous version of each secret is kept to make rotation easier.

Plugin authors get a small set of functions:

Function Purpose
wp_set_secret() Store a value; returns WP_Error on failure
wp_get_secret() Returns a WP_Secret object, null if never stored, or WP_Error if unreadable
WP_Secret::reveal() The only way to get the plain value
wp_import_option_as_secret() Copy an existing option into the store and flag it for rotation
wp_is_secrets_api_available() False if the key or drop-in is unusable

The WP_Secret wrapper prints as [secret:name], and serializing or cloning it throws, which keeps values out of logs and debug dumps by accident. Names follow a plugin-slug/secret-name pattern, and the note adds that the prefix prevents plugins overwriting each other but is not access control. The functions do not check user capabilities, so callers must, especially in cron and REST contexts.

Hosts can replace the keyring, store or provider through a wp-content/secrets.php drop-in, for example to use a hardware key service or an external secret manager. Where a provider is read-only, wp_set_secret() returns an error, and plugins are expected to handle that.

If you tested a beta

The note lists breaking changes since Beta 1. The earlier fallback that derived a key from LOGGED_IN_KEY and LOGGED_IN_SALT is gone, so WP_SECRETS_KEY is now required. The keyring, store and provider classes changed from interfaces to abstract classes, so drop-ins must change implements to extends or cause a fatal error on every request. Anyone with secrets stored under the old fallback gets a migration path using a WP_SECRETS_KEY_PREVIOUS constant and a rotate_site_key command via wp eval. The November 13 correction adds that multi-network installs must re-encrypt each network’s root key, not just the current one.

Not everyone is convinced

Comments under the note show a live disagreement. Ryan McCue opposed the feature, arguing that secrets and application data are being mixed, and suggested separate read-only and read-write APIs; Matt Mullenweg agreed with him. Eric Mann replied that he wanted to keep it in 7.2, citing the read-only provider design and a pending fix in the AI plugin. Peter Wilson pointed out that capability checks mentioned in the proposal are not in the code and opened a ticket, #66696. John Blackbourn said the feature is needed but wants more work and feedback from hosts and plugin developers.

I have not seen a decision recorded, so the safest reading is that the API is in the 7.2 beta and could still change before the final release.

A security feature that does not remove the need for care

DreamHost’s preview, based on the roadmap as of late September, framed the Secrets API as one of several credential changes, alongside planned email alerts for new application passwords and a “sudo mode” that was already marked at risk. It described a management screen as planned for 7.3, so for 7.2 this is plumbing for developers and WP-CLI users, not a button in the dashboard.

My own reading of the design, not a claim from the note: encryption in the options table protects a leaked database dump, but code running inside the site can ask for a value the same way a plugin does, and the key sits in wp-config.php on the same server. That is why the drop-in route to an external secret store looks like the option security-sensitive hosts will want.

What to do before December 8

  1. Test your plugins on a staging copy of the beta; the REST API and Interactivity API dev notes also list breaking changes.
  2. Add WP_SECRETS_KEY to staging first and check that Site Health is green.
  3. Ask the vendors of plugins that hold payment or mail credentials whether they will adopt the API, and how they will migrate existing options.
  4. Store a copy of the key in your password manager.

Sources

  1. Make WordPress Core: The Secrets API in WordPress 7.2 (Eric Mann, Nov 11, corrected Nov 13) make.wordpress.org
  2. DreamHost: What's Coming in WordPress 7.2: A New Default Theme, Suggestion Mode, and Safer Credentials dreamhost.com
  3. Make WordPress Core: WordPress 7.2 development cycle make.wordpress.org