Extension points intended for extension and customization

// Structure of documents
└── src/
    └── Encryption/
        ├── EncryptorInterface.php
    └── KeyManagement/
        ├── KeyGeneratorInterface.php
        ├── KeyRotatorInterface.php
    └── Sodium/
        └── SodiumKeyPairRepositoryInterface.php

Path: /src/Encryption/EncryptorInterface.php

<?php

declare(strict_types=1);

namespace Drupal\easy_encryption\Encryption;

/**
 * Defines an interface for encrypting and decrypting sensitive data.
 */
interface EncryptorInterface {

  /**
   * Encrypts a value.
   *
   * @param string $value
   *   The plaintext value to encrypt.
   *
   * @return \Drupal\easy_encryption\Encryption\EncryptedValue
   *   The encrypted value with metadata.
   *
   * @throws \InvalidArgumentException
   *   If the value is empty.
   * @throws \Drupal\easy_encryption\Encryption\EncryptionException
   *   If encryption fails.
   */
  public function encrypt(#[\SensitiveParameter] string $value): EncryptedValue;

  /**
   * Decrypts a value.
   *
   * @param \Drupal\easy_encryption\Encryption\EncryptedValue $value
   *   The encrypted value to decrypt.
   *
   * @return string
   *   The decrypted plaintext.
   *
   * @throws \Drupal\easy_encryption\Encryption\EncryptionException
   *   If decryption fails.
   */
  public function decrypt(EncryptedValue $value): string;

  /**
   * Validates that encryption and decryption work correctly.
   *
   * Implementations may skip this test silently if the environment does not
   * support decryption (for example, when only a public key is available).
   *
   * @throws \Drupal\easy_encryption\Encryption\EncryptionException
   *   If the self-test fails.
   */
  public function selfTest(): void;

}

Path: /src/KeyManagement/KeyGeneratorInterface.php

<?php

declare(strict_types=1);

namespace Drupal\easy_encryption\KeyManagement;

/**
 * Application service for generating and activating key pairs.
 *
 * This service returns key identifiers, not key material, to keep the
 * application layer decoupled from the underlying cryptographic library.
 */
interface KeyGeneratorInterface {

  /**
   * Generates and persists a key pair.
   *
   * If no ID is provided, the generator MUST create a new identifier.
   *
   * @param string|null $keyPairId
   *   (optional) The key pair identifier to use.
   *
   * @return string
   *   The key pair identifier that was generated.
   *
   * @throws \Drupal\easy_encryption\KeyManagement\KeyGeneratorException
   *   Thrown when key pair generation fails.
   */
  public function generate(?string $keyPairId = NULL): string;

  /**
   * Activates an existing key pair by ID.
   *
   * Activation MUST be allowed when private key is missing, as long as a public
   * key exists (encrypt-only environments).
   *
   * @param string $keyPairId
   *   The key pair identifier.
   *
   * @throws \Drupal\easy_encryption\KeyManagement\KeyGeneratorException
   *   Thrown when activation fails.
   */
  public function activate(string $keyPairId): void;

}

Path: /src/KeyManagement/KeyRotatorInterface.php

<?php

declare(strict_types=1);

namespace Drupal\easy_encryption\KeyManagement;

/**
 * Application service for planning and performing key rotation.
 */
interface KeyRotatorInterface {

  /**
   * Builds a non-mutating plan describing what would change.
   *
   * @throws \Drupal\easy_encryption\KeyManagement\KeyRotationException
   *   If the plan cannot be computed.
   */
  public function plan(bool $includeReencryptCounts = TRUE): KeyRotationPlan;

  /**
   * Rotates the active key and optionally re-encrypts credentials.
   *
   * @throws \Drupal\easy_encryption\KeyManagement\KeyRotationException
   *   If rotation fails, or re-encryption fails and failOnReencryptErrors
   *   is TRUE.
   */
  public function rotate(KeyRotationOptions $options): KeyRotationResult;

}

Path: /src/Sodium/SodiumKeyPairRepositoryInterface.php

<?php

declare(strict_types=1);

namespace Drupal\easy_encryption\Sodium;

/**
 * Provides access to sodium key pairs used for encryption and decryption.
 */
interface SodiumKeyPairRepositoryInterface {

  /**
   * Returns the key pair currently used for new encryption operations.
   *
   * The active key pair is the one that MUST be used when creating new
   * ciphertexts. Implementations MAY return a key pair without a private
   * key in encrypt-only environments, in which case only encryption is
   * possible with the returned object.
   *
   * @throws \Drupal\easy_encryption\Sodium\Exception\SodiumKeyPairNotFoundException
   * @throws \Drupal\easy_encryption\Sodium\Exception\SodiumKeyPairOperationException
   */
  public function getActiveKeyPair(): SodiumKeyPair;

  /**
   * Returns a key pair by its identifier.
   *
   * Implementations MAY omit the private key when the current environment is
   * not allowed to perform decryption.
   *
   * @throws \Drupal\easy_encryption\Sodium\Exception\SodiumKeyPairNotFoundException
   * @throws \Drupal\easy_encryption\Sodium\Exception\SodiumKeyPairOperationException
   */
  public function getKeyPairById(string $id): SodiumKeyPair;

  /**
   * Generates and persists a key pair for the given identifier.
   *
   * This method MUST:
   * - Generate a cryptographically secure libsodium key pair.
   * - Persist the public key.
   * - Persist the private key where appropriate for the environment.
   * - Register the key pair identifier in configuration (easy_encryption.keys),
   *   so the system knows the key pair exists.
   *
   * This method MUST NOT change which key pair is active.
   *
   * @param string $id
   *   The key pair identifier to generate.
   *
   * @throws \Drupal\easy_encryption\Sodium\Exception\SodiumKeyPairOperationException
   *   Thrown if generation or persistence fails.
   */
  public function generateKeyPair(string $id): void;

  /**
   * Marks an existing key pair as the active key pair.
   *
   * Activation MUST succeed even when the private key is not available, as long
   * as the public key exists. This enables encrypt-only environments.
   *
   * @throws \Drupal\easy_encryption\Sodium\Exception\SodiumKeyPairNotFoundException
   * @throws \Drupal\easy_encryption\Sodium\Exception\SodiumKeyPairOperationException
   */
  public function activateKeyPair(string $id): void;

  /**
   * Returns identifiers for all stored key pairs.
   *
   * Implementations MUST return identifiers for all key pairs known to
   * the repository, regardless of whether the corresponding private
   * keys are available in the current environment.
   *
   * @return string[]
   *   An array of key pair identifiers.
   */
  public function listKeyPairIds(): array;

  /**
   * Deletes a key pair by its identifier.
   *
   * Implementations MUST refuse to delete the currently active key pair.
   * Callers SHOULD rotate to a new active key pair before attempting to
   * delete an older one.
   *
   * @param string $id
   *   The key pair identifier to delete.
   *
   * @throws \Drupal\easy_encryption\Sodium\Exception\SodiumKeyPairOperationException
   *   Thrown if the key pair is active, or if deletion fails due to a
   *   storage or permissions error.
   */
  public function deleteKeyPair(string $id): void;

}

---

File Statistics - Size: 7.3 KB - Lines: 261 File: core/api-extension-points.md