[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Secrets API: WP_Secrets_Keyring class
   4   *
   5   * @package WordPress
   6   * @subpackage Secrets
   7   * @since 7.2.0
   8   */
   9  
  10  /**
  11   * Wraps and unwraps the root key that everything else in this API derives from.
  12   *
  13   * A KMS or HSM lives behind this class in a production deployment. An
  14   * implementation is never handed a plaintext secret, only 32 bytes of key material,
  15   * and cannot turn encryption off. There is no method here that
  16   * accepts a plaintext secret value at all.
  17   *
  18   * An implementation should run WP_Secrets_Keyring_Conformance against itself before
  19   * shipping.
  20   *
  21   * Implementations extend this class. It is abstract rather than an interface so
  22   * that a later release can add a method with a default implementation, and every
  23   * existing subclass keeps working.
  24   *
  25   * @since 7.2.0
  26   */
  27  abstract class WP_Secrets_Keyring {
  28  
  29      /**
  30       * Wraps (encrypts) raw key material for storage.
  31       *
  32       * Must not be deterministic: two calls with the same key material must return
  33       * different values. WP_Secrets_Key_Manager::rotate_site_key() stores the
  34       * re-wrapped value with update_site_option(), which reports an unchanged value
  35       * as a failure, and WP_Secrets_Keyring_Conformance checks this.
  36       *
  37       * Attributes are not inherited, so an implementation must mark $key_material
  38       * with #[\SensitiveParameter] itself to keep it out of stack traces.
  39       *
  40       * @since 7.2.0
  41       *
  42       * @param string $key_material Raw key material to protect.
  43       * @return string|WP_Error Opaque wrapped value on success, WP_Error on failure.
  44       */
  45      abstract public function wrap(
  46          #[\SensitiveParameter]
  47          string $key_material
  48      );
  49  
  50      /**
  51       * Unwraps (decrypts) previously wrapped key material.
  52       *
  53       * @since 7.2.0
  54       *
  55       * @param string $wrapped An opaque value previously returned by wrap().
  56       * @return string|WP_Error Raw key material on success, WP_Error on failure.
  57       */
  58      abstract public function unwrap( string $wrapped );
  59  
  60      /**
  61       * A human-readable description of the key source, for Site Health.
  62       *
  63       * @since 7.2.0
  64       *
  65       * @return string
  66       */
  67      abstract public function get_key_source(): string;
  68  }