Sodium bridge (API surface)

domain, sodium

// Structure of documents
└── src/
    └── Sodium/
        └── Exception/
            ├── SodiumKeyPairException.php
            ├── SodiumKeyPairNotFoundException.php
            ├── SodiumKeyPairOperationException.php
        └── SodiumKeyPairReadRepositoryInterface.php
        └── SodiumKeyPairWriteRepositoryInterface.php

Path: /src/Sodium/Exception/SodiumKeyPairException.php

namespace Drupal\easy_encryption\Sodium\Exception;

/**
 * Base exception for sodium key pair repository failures.
 *
 * All exceptions thrown by Sodium repositories
 * implementations SHOULD extend this class so that callers can
 * catch and handle repository errors in a generic way.
 */
class SodiumKeyPairException extends \RuntimeException
{
    /**
     * Creates an exception for a key pair that was not found.
     *
     * @param string $id
     *   The key pair identifier.
     *
     * @return self
     *   The exception instance.
     */
    public static function notFound(string $id): self
    {
        /* ... */
    }
}

Path: /src/Sodium/Exception/SodiumKeyPairNotFoundException.php

namespace Drupal\easy_encryption\Sodium\Exception;

/**
 * Thrown when a requested key pair cannot be found.
 */
final class SodiumKeyPairNotFoundException extends SodiumKeyPairException
{
    /**
     * Creates an exception for a missing key pair identifier.
     *
     * @param string $id
     *   The missing key pair identifier.
     * @param \Throwable|null $previous
     *   (optional) The previous throwable.
     *
     * @return static
     *   The exception instance.
     */
    public static function forId(string $id, ?\Throwable $previous = null): self
    {
        /* ... */
    }


    /**
     * Creates an exception for a missing active key pair.
     *
     * @return self
     *   The exception instance.
     */
    public static function forActive(): self
    {
        /* ... */
    }
}

Path: /src/Sodium/Exception/SodiumKeyPairOperationException.php

namespace Drupal\easy_encryption\Sodium\Exception;

/**
 * Thrown when a key pair operation fails.
 *
 * This exception covers failures related to key pair generation, storage,
 * retrieval, deletion, and cryptographic operations that depend on key
 * availability or validity.
 */
final class SodiumKeyPairOperationException extends SodiumKeyPairException
{
    /**
     * Creates an exception for a failed generation or activation.
     *
     * @param \Throwable|null $previous
     *   (optional) The previous throwable.
     *
     * @return self
     *   The exception instance.
     */
    public static function generationFailed(?\Throwable $previous = null): self
    {
        /* ... */
    }


    /**
     * Creates an exception for a failed load of an existing key pair.
     *
     * @param string $id
     *   The key pair identifier.
     * @param \Throwable|null $previous
     *   (optional) The previous throwable.
     *
     * @return self
     *   The exception instance.
     */
    public static function loadFailed(string $id, ?\Throwable $previous = null): self
    {
        /* ... */
    }


    /**
     * Creates an exception for an attempt to delete the active key pair.
     *
     * @param string $id
     *   The key pair identifier.
     *
     * @return self
     *   The exception instance.
     */
    public static function cannotDeleteActive(string $id): self
    {
        /* ... */
    }


    /**
     * Creates an exception for a failed deletion operation.
     *
     * @param string $id
     *   The key pair identifier.
     * @param \Throwable|null $previous
     *   (optional) The previous throwable.
     *
     * @return self
     *   The exception instance.
     */
    public static function deleteFailed(string $id, ?\Throwable $previous = null): self
    {
        /* ... */
    }


    /**
     * Creates an exception for a failed decryption operation.
     *
     * @param string $keyId
     *   The key pair identifier.
     * @param \Throwable|null $previous
     *   (optional) The previous throwable.
     *
     * @return self
     *   The exception instance.
     */
    public static function decryptionFailed(string $keyId, ?\Throwable $previous = null): self
    {
        /* ... */
    }


    /**
     * Creates an exception when the private key is not available.
     *
     * This typically occurs in encrypt-only environments where the private key
     * has been intentionally excluded for security reasons.
     *
     * @param string $keyId
     *   The key pair identifier.
     *
     * @return self
     *   The exception instance.
     */
    public static function privateKeyNotAvailable(string $keyId): self
    {
        /* ... */
    }


    /**
     * Creates an exception when the public key is not available.
     *
     * @param string $keyId
     *   The key pair identifier.
     *
     * @return self
     *   The exception instance.
     */
    public static function publicKeyNotAvailable(string $keyId): self
    {
        /* ... */
    }


    /**
     * Creates an exception when keypair construction fails.
     *
     * This occurs when sodium_crypto_box_keypair_from_secretkey_and_publickey()
     * throws an exception, typically indicating key corruption or mismatch.
     *
     * @param string $keyId
     *   The key pair identifier.
     * @param \Throwable $previous
     *   The previous throwable from the Sodium operation.
     *
     * @return self
     *   The exception instance.
     */
    public static function keypairConstructionFailed(string $keyId, \Throwable $previous): self
    {
        /* ... */
    }
}

Path: /src/Sodium/SodiumKeyPairReadRepositoryInterface.php

namespace Drupal\easy_encryption\Sodium;

/**
 * Read-only repository for sodium key pairs.
 */
interface SodiumKeyPairReadRepositoryInterface
{
    /**
     * 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;


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

Path: /src/Sodium/SodiumKeyPairWriteRepositoryInterface.php

namespace Drupal\easy_encryption\Sodium;

/**
 * Write repository for sodium key pairs.
 */
interface SodiumKeyPairWriteRepositoryInterface
{
    /**
     * Generates and persists a new key pair with the given id.
     *
     * @throws \Drupal\easy_encryption\Sodium\Exception\SodiumKeyPairOperationException
     *   If generation or persistence fails.
     */
    public function generateKeyPair(string $id): void;


    /**
     * Deletes persisted key material for the given id.
     *
     * @throws \Drupal\easy_encryption\Sodium\Exception\SodiumKeyPairOperationException
     *   If deletion fails.
     */
    public function deleteKeyPair(string $id): void;


    /**
     * Writes/updates public key material.
     *
     * @throws \Drupal\easy_encryption\Sodium\Exception\SodiumKeyPairOperationException
     *   If persistence fails.
     */
    public function upsertPublicKey(string $id, string $publicKeyBin): void;


    /**
     * Writes/updates private key material.
     *
     * @throws \Drupal\easy_encryption\Sodium\Exception\SodiumKeyPairOperationException
     *   If persistence fails.
     */
    public function upsertPrivateKey(string $id, string $privateKeyBin): void;
}

---

File Statistics - Size: 7.39 KB - Lines: 329 File: core/domain/sodium.md