Key transfer domain (API surface)#
// Structure of documents
└── src/
└── KeyTransfer/
└── KeyTransferException.php
└── KeyTransferInterface.php
└── Port/
└── KeyPackageCodecException.php
└── KeyPackageCodecInterface.php
└── KeyTransferPayloadHandlerException.php
└── KeyTransferPayloadHandlerInterface.php
Path: /src/KeyTransfer/KeyTransferException.php#
namespace Drupal\easy_encryption\KeyTransfer;
/**
* Thrown when key transfer operations fail at the application layer.
*/
final class KeyTransferException extends \RuntimeException
{
/**
* Creates an exception for an invalid package.
*
* @param string $reason
* Human-readable validation error.
* @param \Throwable|null $previous
* (optional) The underlying exception.
*/
public static function invalidPackage(string $reason, ?\Throwable $previous = null): self
{
/* ... */
}
/**
* Creates an exception when no payload handler supports the package payload.
*
* @param string $reason
* Human-readable explanation, for example "Unsupported format foo".
* @param \Throwable|null $previous
* (optional) The underlying exception.
*/
public static function unsupportedPayload(string $reason, ?\Throwable $previous = null): self
{
/* ... */
}
/**
* Creates an exception for export failures.
*
* @param string $keyId
* The key id that was being exported.
* @param string $reason
* Human-readable explanation of the failure.
* @param \Throwable|null $previous
* (optional) The underlying exception.
*/
public static function exportFailed(string $keyId, string $reason, ?\Throwable $previous = null): self
{
/* ... */
}
/**
* Creates an exception for import failures.
*
* @param string $reason
* Human-readable explanation of the failure.
* @param \Throwable|null $previous
* (optional) The underlying exception.
*/
public static function importFailed(string $reason, ?\Throwable $previous = null): self
{
/* ... */
}
/**
* Creates an exception for failures while activating a key after import.
*
* @param string $keyId
* The imported key id that could not be activated.
* @param \Throwable|null $previous
* (optional) The underlying exception.
*/
public static function activationFailed(string $keyId, ?\Throwable $previous = null): self
{
/* ... */
}
}
Path: /src/KeyTransfer/KeyTransferInterface.php#
namespace Drupal\easy_encryption\KeyTransfer;
use Drupal\easy_encryption\Encryption\EncryptionKeyId as EncryptionKeyId;
/**
* Application service for importing/exporting keys as portable packages.
*/
interface KeyTransferInterface
{
/**
* Exports a known key as a portable package string.
*
* @throws \Drupal\easy_encryption\KeyTransfer\KeyTransferException
* When export fails or cannot be performed.
*/
public function exportKey(EncryptionKeyId $keyId): string;
/**
* Imports a portable package string & optionally activates the imported key.
*
* @return array{key_id: \Drupal\easy_encryption\Encryption\EncryptionKeyId, activated: bool}
* The imported key id and whether activation was requested/performed.
*
* @throws \Drupal\easy_encryption\KeyTransfer\KeyTransferException
* When import fails or the package is invalid/unsupported.
*/
public function importKey(string $package, bool $activate = false): array;
}
Path: /src/KeyTransfer/Port/KeyPackageCodecException.php#
namespace Drupal\easy_encryption\KeyTransfer\Port;
/**
* Thrown when a key package cannot be encoded or decoded.
*/
final class KeyPackageCodecException extends \RuntimeException
{
/**
* Creates an exception for failures while encoding a key package.
*
* @param \Throwable|null $previous
* (optional) The underlying exception.
*/
public static function encodeFailed(?\Throwable $previous = null): self
{
/* ... */
}
/**
* Creates an exception for failures while decoding a key package.
*
* @param string $reason
* Human-readable error describing what part of decoding failed.
* @param \Throwable|null $previous
* (optional) The underlying exception.
*/
public static function decodeFailed(string $reason, ?\Throwable $previous = null): self
{
/* ... */
}
}
Path: /src/KeyTransfer/Port/KeyPackageCodecInterface.php#
namespace Drupal\easy_encryption\KeyTransfer\Port;
/**
* Encodes/decodes key transfer packages (envelope only).
*
* The codec is format-agnostic: algorithm-specific data is carried in the
* payload structure and interpreted by payload handlers.
*/
interface KeyPackageCodecInterface
{
/**
* Encodes the package structure into a portable string.
*
* @param array<string,mixed> $data
* Package data, typically with keys like 'key_id' and 'payload'.
*
* @throws \Drupal\easy_encryption\KeyTransfer\Port\KeyPackageCodecException
* When the package cannot be encoded.
*/
public function encode(array $data): string;
/**
* Decodes a portable string into the package structure.
*
* @return array<string,mixed>
* Package data.
*
* @throws \Drupal\easy_encryption\KeyTransfer\Port\KeyPackageCodecException
* When the package cannot be decoded.
*/
public function decode(string $text): array;
}
Path: /src/KeyTransfer/Port/KeyTransferPayloadHandlerException.php#
namespace Drupal\easy_encryption\KeyTransfer\Port;
/**
* Thrown when a key transfer payload handler cannot import or export a payload.
*/
final class KeyTransferPayloadHandlerException extends \RuntimeException
{
/**
* Creates an exception for invalid payload content.
*
* @param string $reason
* Human-readable validation error.
* @param \Throwable|null $previous
* (optional) The underlying exception.
*/
public static function invalidPayload(string $reason, ?\Throwable $previous = null): self
{
/* ... */
}
/**
* Creates an exception when exporting a key is not possible.
*
* @param string $keyId
* The key id that could not be exported.
* @param string $reason
* Human-readable explanation.
* @param \Throwable|null $previous
* (optional) The underlying exception.
*/
public static function exportNotPossible(string $keyId, string $reason, ?\Throwable $previous = null): self
{
/* ... */
}
/**
* Creates an exception when importing a key is not possible.
*
* @param string $keyId
* The key id that could not be imported.
* @param string $reason
* Human-readable explanation.
* @param \Throwable|null $previous
* (optional) The underlying exception.
*/
public static function importNotPossible(string $keyId, string $reason, ?\Throwable $previous = null): self
{
/* ... */
}
}
Path: /src/KeyTransfer/Port/KeyTransferPayloadHandlerInterface.php#
namespace Drupal\easy_encryption\KeyTransfer\Port;
use Drupal\easy_encryption\Encryption\EncryptionKeyId as EncryptionKeyId;
/**
* Port for handling algorithm-specific key transfer payloads.
*
* Implementations are discovered via tagged services.
*
* @template TPayload of array
*/
interface KeyTransferPayloadHandlerInterface
{
/**
* Returns TRUE if this handler supports importing the given payload.
*
* This method must be defensive: it can receive any decoded payload data.
*
* @param array $payload
* Payload data.
*
* @phpstan-assert-if-true TPayload $payload
*/
public function applies(array $payload): bool;
/**
* Exports key material as payload data.
*
* @return TPayload
* Payload data for this handler.
*
* @throws \Drupal\easy_encryption\KeyTransfer\Port\KeyTransferPayloadHandlerException
* When export cannot be performed.
*/
public function exportPayload(EncryptionKeyId $keyId): array;
/**
* Imports key material from payload data for the provided key id.
*
* This method must not activate the key. Activation is application logic.
*
* @param \Drupal\easy_encryption\Encryption\EncryptionKeyId $keyId
* Key identifier from the package envelope.
* @param TPayload $payload
* Payload data for this handler.
*
* @throws \Drupal\easy_encryption\KeyTransfer\Port\KeyTransferPayloadHandlerException
* When import cannot be performed.
*/
public function importPayload(EncryptionKeyId $keyId, array $payload): void;
}
File Statistics
- Size: 8.43 KB
- Lines: 336
File: core/domain/key_transfer.md