- md5
- 2123c606b2b5231738da665742905b64
- sha1
- 292fccbeab1392ce22b4ef46a0438fed8872c967
- sha256
- 70648bd8f17256fc598b44a98e56acaf668e5498936ecfd049f7ba514152f003
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308
<?php
/**
* Secrets API: WP_Secrets_Config_Key_Provider class
*
* @package WordPress
* @subpackage Secrets
* @since 7.2.0
*/
/**
* The default keyring.
*
* Derives a site key from wp-config.php and uses it to wrap and unwrap the root key
* with authenticated encryption.
*
* Site key derivation, in priority order:
*
* 1. WP_SECRETS_KEY is defined and base64-decodes (strictly) to exactly 32 bytes:
* those decoded bytes are used raw. This is the documented, recommended form;
* `wp secret generate-key` emits it.
* 2. WP_SECRETS_KEY is defined in any other shape: the literal constant string is
* hashed with a keyed BLAKE2b to 32 bytes. This is the legacy interpretation –
* sites arriving from a prior plugin with a constant of arbitrary shape are not
* locked out of their own credentials by a hard failure here.
* 3. WP_SECRETS_KEY is undefined: LOGGED_IN_KEY . LOGGED_IN_SALT is hashed the same
* way. Deliberately byte-identical to the legacy interpretation's hashing, not a
* coincidence – it is what makes salt-fallback sites migrate with zero
* credential re-entry.
*
* WP_SECRETS_KEY_PREVIOUS follows the same three rules and exists only so a site-key
* rotation can unwrap under the old key before wrapping under the new one.
*
* @since 7.2.0
*/
final class WP_Secrets_Config_Key_Provider implements WP_Secrets_Keyring {
/**
* AAD binding the root key's wrapped form to this purpose.
*
* Prevents the wrapped root key from being replayed as some other wrapped value.
*
* @since 7.2.0
* @var string
*/
const AAD = 'wp-secrets-root-key-v1';
/**
* The exact text wp-config-sample.php ships for every auth and salt constant.
*
* A site running with this literal value never ran the secret-key generator.
* Treating it as usable would derive a key that any attacker can also derive.
*
* @since 7.2.0
* @var string
*/
const KNOWN_PLACEHOLDER = 'put your unique phrase here';
/**
* Whether to derive from WP_SECRETS_KEY_PREVIOUS instead of WP_SECRETS_KEY.
*
* @since 7.2.0
* @var bool
*/
private $use_previous_key;
/**
* Constructor.
*
* @since 7.2.0
*
* @param bool $use_previous_key Derive from WP_SECRETS_KEY_PREVIOUS rather than
* WP_SECRETS_KEY. Used only during a site-key
* rotation, to unwrap under the outgoing key.
*/
public function __construct( bool $use_previous_key = false ) {
$this->use_previous_key = $use_previous_key;
}
/**
* Wraps raw key material under the derived site key.
*
* @since 7.2.0
*
* @param string $key_material Raw key material to protect.
* @return string|WP_Error
*/
public function wrap( string $key_material ) {
if ( '' === $key_material ) {
return new WP_Error(
WP_SECRETS_ERROR_INVALID_VALUE,
__( 'Key material to wrap must not be empty.' )
);
}
if ( ! function_exists( 'sodium_crypto_aead_xchacha20poly1305_ietf_encrypt' ) ) {
return new WP_Error(
WP_SECRETS_ERROR_CRYPTO_UNAVAILABLE,
__( 'No libsodium implementation is available.' )
);
}
$site_key = $this->get_site_key();
if ( is_wp_error( $site_key ) ) {
return $site_key;
}
$nonce = random_bytes( SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_NPUBBYTES );
$ciphertext = sodium_crypto_aead_xchacha20poly1305_ietf_encrypt( $key_material, self::AAD, $nonce, $site_key );
wp_secrets_memzero( $site_key );
return base64_encode( $nonce . $ciphertext );
}
/**
* Unwraps key material previously wrapped by wrap().
*
* @since 7.2.0
*
* @param string $wrapped An opaque value previously returned by wrap().
* @return string|WP_Error
*/
public function unwrap( string $wrapped ) {
if ( '' === $wrapped ) {
return new WP_Error(
WP_SECRETS_ERROR_KEY_UNAVAILABLE,
__( 'Nothing to unwrap.' )
);
}
if ( ! function_exists( 'sodium_crypto_aead_xchacha20poly1305_ietf_decrypt' ) ) {
return new WP_Error(
WP_SECRETS_ERROR_CRYPTO_UNAVAILABLE,
__( 'No libsodium implementation is available.' )
);
}
$raw = base64_decode( $wrapped, true );
$nonce_length = SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_NPUBBYTES;
if ( false === $raw || strlen( $raw ) <= $nonce_length ) {
return new WP_Error(
WP_SECRETS_ERROR_KEY_UNAVAILABLE,
__( 'The wrapped key material is malformed.' )
);
}
$nonce = substr( $raw, 0, $nonce_length );
$ciphertext = substr( $raw, $nonce_length );
$site_key = $this->get_site_key();
if ( is_wp_error( $site_key ) ) {
return $site_key;
}
$key_material = sodium_crypto_aead_xchacha20poly1305_ietf_decrypt( $ciphertext, self::AAD, $nonce, $site_key );
wp_secrets_memzero( $site_key );
if ( ! is_string( $key_material ) ) {
return new WP_Error(
WP_SECRETS_ERROR_KEY_UNAVAILABLE,
__( 'The wrapped key material could not be decrypted with the configured site key.' )
);
}
return $key_material;
}
/**
* Describes the active key source, for Site Health.
*
* @since 7.2.0
*
* @return string
*/
public function get_key_source(): string {
if ( defined( 'WP_SECRETS_KEY' ) ) {
return $this->is_canonical_base64_32( WP_SECRETS_KEY )
? 'WP_SECRETS_KEY (base64-encoded 32 bytes)'
: 'WP_SECRETS_KEY (legacy interpretation, hashed as an opaque string)';
}
return 'derived from LOGGED_IN_KEY and LOGGED_IN_SALT';
}
/**
* Derives the 32-byte site key per the priority rules documented on this class.
*
* @since 7.2.0
*
* @return string|WP_Error
*/
private function get_site_key() {
$constant_name = $this->use_previous_key ? 'WP_SECRETS_KEY_PREVIOUS' : 'WP_SECRETS_KEY';
if ( defined( $constant_name ) ) {
$raw_constant = constant( $constant_name );
if ( ! is_string( $raw_constant ) || '' === $raw_constant ) {
return new WP_Error(
WP_SECRETS_ERROR_KEY_UNAVAILABLE,
sprintf(
/* translators: %s: PHP constant name. */
__( '%s is defined but is not a usable string.' ),
$constant_name
)
);
}
$decoded = $this->decode_canonical_base64_32( $raw_constant );
if ( null !== $decoded ) {
return $decoded;
}
return sodium_crypto_generichash( $raw_constant, '', SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_KEYBYTES );
}
if ( $this->use_previous_key ) {
return new WP_Error(
WP_SECRETS_ERROR_KEY_UNAVAILABLE,
__( 'WP_SECRETS_KEY_PREVIOUS is not defined.' )
);
}
$logged_in_key = defined( 'LOGGED_IN_KEY' ) ? LOGGED_IN_KEY : null;
$logged_in_salt = defined( 'LOGGED_IN_SALT' ) ? LOGGED_IN_SALT : null;
if ( ! $this->are_usable_salt_values( $logged_in_key, $logged_in_salt ) ) {
return new WP_Error(
WP_SECRETS_ERROR_KEY_UNAVAILABLE,
__( 'WP_SECRETS_KEY is not defined, and LOGGED_IN_KEY/LOGGED_IN_SALT are not usable (undefined, empty, or left at the wp-config-sample.php placeholder).' )
);
}
return sodium_crypto_generichash( $logged_in_key . $logged_in_salt, '', SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_KEYBYTES );
}
/**
* Whether a pair of candidate salt values are usable as key material.
*
* Both must be non-empty strings, and neither may be the literal
* wp-config-sample.php placeholder – which every unconfigured install shares,
* making it a publicly known value rather than a secret.
*
* Takes explicit arguments rather than reading LOGGED_IN_KEY/LOGGED_IN_SALT
* directly so the decision logic is testable without touching real constants,
* which – once WordPress has bootstrapped once in a process – can never be
* redefined to a different value for a test.
*
* @since 7.2.0
*
* @param mixed $logged_in_key Candidate value of LOGGED_IN_KEY, or null if undefined.
* @param mixed $logged_in_salt Candidate value of LOGGED_IN_SALT, or null if undefined.
* @return bool
*
* @phpstan-assert-if-true non-empty-string $logged_in_key
* @phpstan-assert-if-true non-empty-string $logged_in_salt
*/
private function are_usable_salt_values( $logged_in_key, $logged_in_salt ): bool {
return array_all(
array( $logged_in_key, $logged_in_salt ),
fn( $value ) => is_string( $value ) && '' !== $value && self::KNOWN_PLACEHOLDER !== $value
);
}
/**
* Whether $value is the canonical base64 encoding of exactly 32 bytes.
*
* Uses strict-mode decoding plus a re-encode comparison, rather than a bare
* base64_decode(), so that a malformed or non-canonically-padded constant falls
* through to the legacy (hashed) interpretation instead of being silently
* accepted as 32 bytes of something else.
*
* @since 7.2.0
*
* @param mixed $value Candidate value.
* @return bool
*/
private function is_canonical_base64_32( $value ): bool {
return null !== $this->decode_canonical_base64_32( $value );
}
/**
* Decodes $value if it is the canonical base64 encoding of exactly 32 bytes.
*
* @since 7.2.0
*
* @param mixed $value Candidate value.
* @return string|null The 32 decoded bytes, or null if $value is anything else.
*/
private function decode_canonical_base64_32( $value ): ?string {
if ( ! is_string( $value ) ) {
return null;
}
$decoded = base64_decode( $value, true );
if ( false === $decoded || SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_KEYBYTES !== strlen( $decoded ) ) {
return null;
}
return base64_encode( $decoded ) === $value ? $decoded : null;
}
}
The same content is in 3 releases, WordPress 7.2-beta2 to 7.2-beta4. See them all, or every version of this file.