Enterprise редакция

Contracts — глубокий справочник

Кратко

Модуль Contracts — это интеграционный шов Enterprise для клиентов RFC 3161 Time Stamp Authority.

TsaClientInterface объявляет одну операцию: запросить DER-кодированный TimeStampToken для заранее вычисленного дайджеста документа.
TsaClientAdapter подключает клиент меток времени Core, класс final, к этому интерфейсу без изменения поведения.
Компоненты Enterprise, такие как LtvManager и DocumentTimestamp, принимают интерфейс, поэтому поведение TSA внедряемо и заменяемо в тестах.
Через шов проходит только хеш документа; содержимое документа — никогда.

Для рекомендаций по рабочим процессам сначала прочитайте страницу возможности Contracts.

Доступность и лицензирование

Эта возможность поставляется в NextPDF Enterprise (nextpdf/enterprise) и активируется лицензионным конвертом уровня Enterprise. Развёртывание без такого права не загружает классы этой возможности. Сравните редакции и получите лицензию.

Интерфейс не выполняет работы и ничего не закрывает сам по себе. Потребляющие поверхности Enterprise применяют собственные коды возможностей, например enterprise.compliance.evidence на поверхности compliance-evidence.

Уровень	Предоставляет
Core	Конкретный `TsaClient` (`final`), выполняющий запросы RFC 3161
Pro	Эквивалента модуля Contracts нет
Enterprise	Шов `TsaClientInterface` и мост `TsaClientAdapter`

composer require nextpdf/enterprise:^3

Публичная поверхность API

Символ	Параметры	Поведение по умолчанию	Возвращает	Бросает или завершается ошибкой	Примечания
`TsaClientInterface::getDocumentTimestamp()`	`string $documentHash`	Объявляет запрос токена метки времени для заранее вычисленного дайджеста документа	`string` — DER-кодированный TimeStampToken	Определяется реализацией; интерфейс не объявляет исключений	Единственная операция; исходный код документирует ввод дайджеста SHA-256
`TsaClientAdapter::__construct()`	`TsaClient $client`	Сохраняет клиент меток времени Core	`TsaClientAdapter`	Ничего не объявлено	`final readonly`; продвижение конструктора
`TsaClientAdapter::getDocumentTimestamp()`	`string $documentHash`	Передаёт в `TsaClient::getDocumentTimestamp()` без изменений	`string` — DER-кодированный TimeStampToken	`TsaException` от клиента Core, переданное без изменений	Не добавляет поведения; ничего не проглатывает

namespace NextPDF\Enterprise\Contracts;

interface TsaClientInterface
{
    /**
     * Request a timestamp token for a document hash.
     *
     * @param string $documentHash SHA-256 digest of the document content
     *
     * @return string DER-encoded TimeStampToken
     */
    public function getDocumentTimestamp(string $documentHash): string;
}

namespace NextPDF\Enterprise\Contracts;

use NextPDF\Security\Timestamp\TsaClient;

final readonly class TsaClientAdapter implements TsaClientInterface
{
    public function __construct(
        private TsaClient $client,
    )

    public function getDocumentTimestamp(string $documentHash): string
}

Контракт поведения

TsaClientInterface::getDocumentTimestamp(string $documentHash): string возвращает DER-кодированный TimeStampToken по RFC 3161 для хеша документа. Внешне наблюдаемые правила:

Интерфейс объявляет одну операцию; он не проверяет токен, не ручается за TSA и не утверждает юридического эффекта.
TsaClientAdapter передаёт вызов клиенту меток времени Core без изменений — без добавленного поведения, без добавленных повторов, без проглоченных исключений, без дополнительных гарантий. Его единственная цель — позволить final-клиенту Core удовлетворять обращённый к Enterprise интерфейс для инверсии зависимостей и тестирования.
Через границу проходит только хеш документа; содержимое документа не передаётся.
За адаптером клиент Core отклоняет дайджест, длина которого не совпадает с его настроенным алгоритмом отпечатка, с TsaException, отказоустойчиво, до какой-либо сетевой активности. Иначе неверно помеченный отпечаток дал бы токен, который не сможет привязать ни один соответствующий валидатор.
Потребляющие поверхности: LtvManager принимает необязательный TsaClientInterface и требует его для PAdES B-LTA. DocumentTimestamp использует контракт для заполнения /Contents словаря подписи /DocTimeStamp. Исполнитель обновления LTV-архива (LtvaRenewalExecutor) подключает TsaClientAdapter вокруг клиента Core при обновлении меток времени документа.

Граничные случаи и режимы сбоя

Адаптер передаёт исключения от нижележащего клиента без изменений; сбои TSA должны обрабатываться в месте вызова.
Дайджест должен быть сырыми двоичными данными в соответствии с настроенным алгоритмом отпечатка конкретного клиента (по умолчанию SHA-256, 32 байта). Дайджест в шестнадцатеричной кодировке имеет неверную длину и отклоняется до отправки какого-либо запроса.
Возвращённый токен — это байты, а не вердикт; проверяйте его там, где это требуется.
Собственная реализация владеет собственной поверхностью сбоев. Контракт фиксирует только форму возврата: DER-кодированный TimeStampToken.

Поведение в режиме FIPS

Этот модуль не выполняет криптографических операций. Выбор алгоритма и поведение в режиме FIPS управляются конкретным TSA-клиентом и модулем Security. См. глубокий справочник по FIPS 140.

Соответствие

Поведение	Ссылка
Запрос токена метки времени и привязка	IETF RFC 3161 §2
TimeStampReq несёт MessageImprint: идентификатор алгоритма хеширования и хеш данных, подлежащих проставлению метки времени	IETF RFC 3161 §2.4.1
messageImprint токена должен совпадать со значением запроса, а размер хеша — соответствовать идентифицированному алгоритму	IETF RFC 3161 §2.4.2

Контракт построен вокруг RFC 3161; фактический запрос токена и любая проверка выполняются конкретным клиентом и поверхностями Evidence/Signature. Интерфейс не делает заявлений о соответствии или аттестации. NextPDF не делает заявлений о сертификации.

Замечания по разработке

Оба типа несут @since 3.0.0; этот справочник документирует поверхность в том виде, в каком она поставляется в nextpdf/enterprise 3.1.0.
Внедряйте TsaClientInterface в компоненты, которым нужны метки времени; подключайте TsaClientAdapter или собственную реализацию в корне композиции. В модульных тестах подставляйте тестовый дублёр вместо живого TSA.
Оператор владеет конкретным TSA-клиентом за адаптером: резидентность, граница доверия конечной точки TSA и проверка цепочки сертификатов применяются к этому клиенту, а не к этому интерфейсу.
К этой контрактной поверхности не применяется ограничение экспортного контроля. Получение токена метки времени поддерживает рабочие процессы аудита и долгосрочной проверки; это не юридическая аттестация и не сертификация. Этот справочник не является юридическим заключением.
Детали внутреннего механизма остаются во внутренней документации репозитория исходного кода и находятся вне области действия этого руководства.

Граница публикации

Эта страница документирует только внешне наблюдаемое поведение и поддерживаемую публичную поверхность API. Внутренние пути пространств имён, вспомогательные классы, таблицы механизмов, имена файлов runbook и префиксы тикетов находятся вне области действия.