[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Secrets API: WP_Secrets_Keyring interface
   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 interface 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   * @since 7.2.0
  22   */
  23  interface WP_Secrets_Keyring {
  24  
  25      /**
  26       * Wraps (encrypts) raw key material for storage.
  27       *
  28       * Must not be deterministic: two calls with the same key material must return
  29       * different values. WP_Secrets_Key_Manager::rotate_site_key() stores the
  30       * re-wrapped value with update_site_option(), which reports an unchanged value
  31       * as a failure, and WP_Secrets_Keyring_Conformance checks this.
  32       *
  33       * @since 7.2.0
  34       *
  35       * @param string $key_material Raw key material to protect.
  36       * @return string|WP_Error Opaque wrapped value on success, WP_Error on failure.
  37       */
  38  	public function wrap( string $key_material );
  39  
  40      /**
  41       * Unwraps (decrypts) previously wrapped key material.
  42       *
  43       * @since 7.2.0
  44       *
  45       * @param string $wrapped An opaque value previously returned by wrap().
  46       * @return string|WP_Error Raw key material on success, WP_Error on failure.
  47       */
  48  	public function unwrap( string $wrapped );
  49  
  50      /**
  51       * A human-readable description of the key source, for Site Health.
  52       *
  53       * @since 7.2.0
  54       *
  55       * @return string
  56       */
  57  	public function get_key_source(): string;
  58  }