Encryption domain (API surface)

domain, encryption

// Structure of documents
└── src/
    └── Encryption/
        └── EncryptedValue.php
        └── EncryptionException.php
        └── EncryptionKeyId.php
        └── EncryptorInterface.php

Path: /src/Encryption/EncryptedValue.php

namespace Drupal\easy_encryption\Encryption;

/**
 * Immutable value object representing encrypted data with key metadata.
 *
 * The ciphertext is stored internally as raw binary data. Use
 * getCiphertextHex() for storage in configuration, databases, or files that
 * expect string data.
 *
 * @immutable
 */
final class EncryptedValue
{
    public function __construct(
        private readonly string $ciphertext,
        public readonly EncryptionKeyId $keyId,
    ) {
        /* ... */
    }


    /**
     * Returns the raw binary ciphertext.
     *
     * @return string
     *   The binary ciphertext.
     */
    public function getCiphertext(): string
    {
        /* ... */
    }


    /**
     * Returns hex-encoded ciphertext for storage.
     *
     * Use this method when persisting encrypted data to configuration, databases,
     * or files. To reconstruct the object from stored hex, use
     * EncryptedValue::fromHex().
     *
     * @return string
     *   The hex-encoded ciphertext.
     */
    public function getCiphertextHex(): string
    {
        /* ... */
    }


    /**
     * Creates an EncryptedValue from hex-encoded ciphertext.
     *
     * Use this factory method when reading encrypted data from storage that was
     * previously encoded with getCiphertextHex().
     *
     * @param string $hex
     *   The hex-encoded ciphertext.
     * @param string $keyId
     *   The key pair identifier.
     *
     * @return static
     *   A new EncryptedValue instance.
     *
     * @throws \InvalidArgumentException
     *   If the ciphertext is empty or invalid, or the key ID is empty.
     */
    public static function fromHex(string $hex, string $keyId): self
    {
        /* ... */
    }
}

Path: /src/Encryption/EncryptionException.php

namespace Drupal\easy_encryption\Encryption;

/**
 * Thrown when an encryption or decryption operation fails.
 */
class EncryptionException extends \RuntimeException
{
}

Path: /src/Encryption/EncryptionKeyId.php

namespace Drupal\easy_encryption\Encryption;

/**
 * Value object representing an Encryption key identifier.
 *
 * Instances are immutable and always contain a safe, normalized identifier
 * consisting only of lowercase letters, digits, and underscores.
 *
 * This is a shared domain concept used by both key management (generation,
 * rotation, transfer) and encryption (encryptors/ciphertexts). It is not the
 * same as a Key module Key entity ID.
 */
final class EncryptionKeyId implements \Stringable
{
    private const NORMALIZED_PATTERN = '/^[a-z0-9_]+$/';

    /**
     * Creates a EncryptionKeyId from arbitrary input by normalizing it.
     *
     * Normalization rules:
     * - lowercases
     * - replaces any run of characters not in [a-z0-9_] with a single underscore
     * - trims leading/trailing underscores.
     */
    public static function fromUserInput(string $keyId): self
    {
        /* ... */
    }


    /**
     * Creates a EncryptionKeyId from an already-normalized value.
     */
    public static function fromNormalized(string $keyId): self
    {
        /* ... */
    }


    /**
     * {@inheritdoc}
     */
    public function __toString(): string
    {
        /* ... */
    }
}

Path: /src/Encryption/EncryptorInterface.php

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;
}

---

File Statistics - Size: 4.75 KB - Lines: 223 File: core/domain/encryption.md