| title | Host-managed keys |
|---|---|
| description | How a hosting platform owns a site's encryption key: generating it, keeping it out of backups, rotating it, and keeping a history of past keys. |
A common question from hosts: can the platform generate and hold a site's encryption key itself,
out of wp-config.php and out of backups, and own its rotation? Yes. That is what the keyring
extension point is for, and nothing in core has to change to do it. This page explains which part
of the key hierarchy a host takes over, then describes three ways to do it, from least to most
work.
Four layers of keys sit between a site and its secrets. The full construction is in envelope-encryption.md. The two outermost layers are the ones that matter here:
| Layer | Where it lives | Who can own it |
|---|---|---|
| Wrapping key (the "site key") | WP_SECRETS_KEY by default, or a host service |
The host |
| Root key, 32 random bytes | The _wp_secrets_root_key site option, wrapped |
WordPress generates it once |
| Master keys, data keys | Derived or generated per secret | WordPress |
The wrapping key is the only key the host needs to own. WordPress generates the root key, but it stores only the wrapped form, and the root key never leaves the site in plaintext. Every master key and data key derives from the root key. Rotating the wrapping key therefore re-wraps one 32-byte value and re-encrypts no secrets.
The consequence for backups is the one hosts care about: a database dump holds ciphertext and a wrapped root key, and neither is usable without the wrapping key. If the wrapping key sits somewhere the backup does not reach, the backup cannot decrypt anything on its own.
This needs no code. The default keyring reads a PHP constant, and the constant can come from
anywhere wp-config.php can read:
// wp-config.php
define( 'WP_SECRETS_KEY', getenv( 'WP_SECRETS_KEY' ) );The host generates the value (wp secret generate-key, or any 32 random bytes, base64-encoded)
and injects it from the hosting panel. wp-config.php then holds a reference instead of the key,
so a file backup no longer carries it.
If the variable goes missing, getenv() returns false, and the keyring treats a constant that
is defined but not a non-empty string as an error. Every secret read then fails closed with
secret_key_unavailable. It never falls back to the salts or to an empty key.
Rotating. Rotation needs both keys for as long as one command takes to run:
- Expose the old value as
WP_SECRETS_KEY_PREVIOUSand the new one asWP_SECRETS_KEY. - Run
wp secret rotate. It unwraps the root key with the previous key and re-wraps it with the current one. - Remove
WP_SECRETS_KEY_PREVIOUS.
The panel can keep as many past values as it likes; WordPress only ever needs the one it is
rotating away from. WP_SECRETS_KEY is required, so a site without it can't use the API. A site
that stored secrets under the salt-derived key of 0.4.0 and earlier, or of a 7.2 beta, has the
string LOGGED_IN_KEY . LOGGED_IN_SALT as its "previous" value. Setting that as
WP_SECRETS_KEY_PREVIOUS moves the site onto a host-issued key the same way.
The limit. An environment variable is still visible to the PHP process. It can end up in
phpinfo(), in $_SERVER or $_ENV under some SAPI configurations, and in an error tracker that
captures the environment. That exposure is narrower than a key in wp-config.php, but it is not
zero. If "doesn't get dumped accidentally" is a hard requirement, use option 2.
In this option the wrapping key never enters PHP at all. A WP_Secrets_Keyring is three methods,
and the host implements wrap() and unwrap() by calling whatever it already runs: a PHP
extension function, a local agent over a Unix socket, a metadata endpoint, or its KMS.
// wp-content/secrets.php, installed and owned by the host.
final class Host_Panel_Keyring extends WP_Secrets_Keyring {
public function wrap( $key_material ) {
// The host's function wraps under the site's newest key version and
// returns an opaque string that records which version it used.
$wrapped = host_panel_wrap( $key_material );
return false === $wrapped
? new WP_Error( WP_SECRETS_ERROR_KEY_UNAVAILABLE, 'Host key service unavailable.' )
: $wrapped;
}
public function unwrap( $wrapped ) {
// Reads the version from $wrapped and unwraps with that version,
// current or retained.
$key_material = host_panel_unwrap( $wrapped );
return false === $key_material
? new WP_Error( WP_SECRETS_ERROR_KEY_UNAVAILABLE, 'Host key service could not unwrap the root key.' )
: $key_material;
}
public function get_key_source() {
return 'Host panel key service';
}
}
$GLOBALS['wp_secrets_keyring'] = new Host_Panel_Keyring();host_panel_wrap() and host_panel_unwrap() stand in for whatever the platform provides. They
are not WordPress functions. Everything else stays WordPress's: the libsodium envelope, the
options-table storage, the wp secret commands. Site Health reports the key source as the host's.
What this gets the host:
- Nothing to leak from PHP. The wrapping key stays inside the host's service. PHP only ever sees the unwrapped root key, in memory for one request. ADR 0009 keeps it out of the object cache.
- One call per request. The key manager unwraps once and caches the result for the rest of the request, however many secrets the request reads.
- Backups are inert.
secrets.phpholds code, not a key, so it can be backed up along with the rest of the site. - Key history on the host's side. If the wrapped value carries a key version, which is how
AWS KMS, Google Cloud KMS, and Vault Transit all work,
unwrap()can use any version the host still retains. The host can then issue a new version without touching the site: the stored root key keeps unwrapping under the version that wrapped it. The host decides how many versions to keep and for how long. - Fails closed. If the service is down,
unwrap()returns aWP_Errorand every secret read reportssecret_key_unavailable. The request never gets an empty value and never falls back towp-config.php. ADR 0007 covers the case where the drop-in itself breaks.
wrap() must be non-deterministic, and unwrap() must return WP_Error for anything it did not
produce and must never throw. The
keyring contract and its conformance suite,
WP_Secrets_Keyring_Conformance, check both. The
AWS KMS keyring example is a complete, tested
implementation of this option, about 300 lines with no SDK.
Moving an existing site onto the host keyring: install the drop-in, then run
wp secret rotate --from=config in the same maintenance window. The command unwraps the root key
with WP_SECRETS_KEY (or the salts) and re-wraps it under the host keyring. Between the two steps,
reads fail closed.
Retiring an old key version means re-wrapping the root key under the newest version. There is
no wp secret rotate option for re-wrapping within the same drop-in keyring yet. Because a
versioned unwrap() keeps reading old versions, this matters only when the host wants to destroy
a version. It is tracked in
open-questions.md.
A host whose panel already stores credentials, and not only keys, can go one level further. In
that case WordPress stops being the custodian at all. A WP_Secrets_Provider takes the value
over an authenticated channel, and the platform stores and encrypts it. Site Health reports
Encryption boundary: the provider (outside WordPress), and the platform's own version history
backs the API's two slots, CURRENT and PREVIOUS.
That requires eight methods instead of three, and the host has to agree to run a secret store. The AWS Secrets Manager and HashiCorp Vault examples show what it looks like. Both are described in examples.md.
| You want | Use |
|---|---|
The key out of wp-config.php and file backups, with no code |
Option 1, an environment variable |
| The key never readable by PHP, with rotation and key history owned by the host | Option 2, a host keyring |
| The host to hold the credentials themselves, not just the key | Option 3, a host provider |
Most hosts want option 2. It is the smallest piece of code that moves key custody off the site, and it leaves storage and encryption exactly as they are on every other WordPress install.