Настройка TSA

Краткий обзор

NextPDF обращается к службе меток времени (TSA) только тогда, когда вы подписываете на уровне PAdES B-T или выше. На уровне B-B метки времени нет и сетевой запрос не выполняется, поэтому эта страница не относится к подписи B-B.

Чтобы B-T работал «из коробки», NextPDF поставляется со встроенной службой TSA по умолчанию. Эта служба по умолчанию — это удобство: она позволяет подписи с меткой времени успешно сформироваться без дополнительной настройки. Она не является публично доверенной и не квалифицирована по eIDAS, поэтому не подходит для промышленного или нормативно-значимого использования без осознанного выбора. На этой странице подробно объясняется, что именно представляет собой служба по умолчанию, как направить NextPDF на вашу собственную TSA, как отключить простановку меток времени и какие есть два пути перехода.

Три свойства независимы и их нельзя путать:

самостоятельно размещаемая (self-hosted) — кто эксплуатирует сервер и к какому корню привязывается цепочка его сертификата;
публично доверенная (publicly-trusted) — доверяет ли экосистема проверки, которую используют ваши доверяющие стороны (их хранилище доверия или список доверия), уже этому корню без ручной настройки, в отличие от ситуации, когда требуется вручную установить частный корень. Речь идёт о якорях доверия доверяющей стороны, а не о какой-либо отдельной программе, такой как Web PKI;
квалифицированная по eIDAS (eIDAS-qualified) — обладает ли метка времени квалифицированной юридической силой в ЕС.

Поставляемая служба по умолчанию является только самостоятельно размещаемой. Публично доверенная TSA добавляет второе свойство. Квалифицированная по eIDAS TSA дополнительно обладает квалифицированным юридическим статусом, проверяемым через доверенные списки ЕС, и может эксплуатироваться сторонним QTSP. Эти три свойства независимы — наличие одного не подразумевает другого.

Встроенная служба TSA по умолчанию

Конечная точка по умолчанию — https://timestamp.pateon.com.tw, собственный сервер простановки меток времени RFC 3161 от NextPDF. Она является самостоятельно размещаемой: сертификат её модуля простановки меток времени привязывается к частному корню PATEON, а не к публичной программе доверия. Поэтому доверяющая сторона не может проверить метку времени, выданную службой по умолчанию, если она не установила и не доверяет этому корню PATEON вне основного канала.

Поскольку токен RFC 3161 не несёт внешнего подтверждения того, что заявленное время верно, доверие к любой такой метке времени полностью основывается на доверии к выпускающей TSA (ISO/IEC 18014-2 §7.3). Для поставляемой службы по умолчанию этот якорь доверия является частным, поэтому она является службой для удобства и разработки, а не нормативно-пригодной.

Когда используется конечная точка по умолчанию и в вашем фреймворке настроен логгер, NextPDF при запуске процесса выдаёт однократное предупреждение о том, что служба по умолчанию не является публично доверенной, и указывающее на эту конфигурацию. Предупреждение носит информационный характер; подписание при этом всё равно проходит успешно.

Переопределение службы по умолчанию

Задайте конечную точку TSA в конфигурации адаптера вашего фреймворка. Точный ключ различается в зависимости от адаптера (см. таблицу по фреймворкам): в Laravel это переменная окружения NEXTPDF_TSA_URL, в Symfony узел бандла nextpdf.tsa.url, а в CodeIgniter ключ окружения nextPdf.tsa.url.

Действующая TSA определяется по следующему приоритету, от высшего к низшему:

Явный TsaClient, который вы создаёте и внедряете самостоятельно, — он всегда побеждает.
URL, заданный в вашем адаптере, — используется, когда вы не внедряете клиент.
Встроенная служба по умолчанию — используется только тогда, когда не задано ни одно из вышеперечисленного.

# Laravel (.env): use your own publicly-trusted TSA instead of the shipped default.
NEXTPDF_TSA_URL=http://timestamp.digicert.com

Отключение метки времени

Если оставить URL TSA вашего адаптера на значении по умолчанию (без настройки), сохраняется встроенная конечная точка по умолчанию. Установка этого URL в пустое значение — это другое: это отключает простановку меток времени. Когда TSA не настроена, подпись, запрошенная на уровне B-T или выше, завершается отказом по принципу fail-closed с ошибкой «TSA required», а не молча понижается до B-B.

# Laravel (.env):
# NEXTPDF_TSA_URL unset -> use the built-in default (timestamp succeeds against pateon).
# NEXTPDF_TSA_URL empty -> no TSA; a B-T+ request fails closed.
NEXTPDF_TSA_URL=

Выбор алгоритма дайджеста для messageImprint

Запрос метки времени RFC 3161 содержит messageImprint — хеш данных, для которых проставляется метка времени, — и по умолчанию NextPDF использует для этого отпечатка SHA-256. Это значение по умолчанию — осознанный выбор, обеспечивающий совместимость; менять его требуется редко.

Когда вы создаёте TsaClient вручную, вы можете выбрать другой дайджест отпечатка через параметр конструктора imprintHashAlgorithm, который принимает значение перечисления TsaImprintHashAlgorithm: Sha256 (по умолчанию), Sha384, Sha512, Sha3_256, Sha3_384 или Sha3_512. Значение по умолчанию сохраняет каждый отправляемый запрос побайтово идентичным предыдущим выпускам, поэтому обновление ничего не меняет, если вы явно не выберете другой вариант.

use NextPDF\Security\Timestamp\TsaClient;
use NextPDF\Security\Timestamp\TsaImprintHashAlgorithm;

// Default — SHA-256 imprint, unchanged from earlier releases:
$tsa = new TsaClient('https://timestamp.example.com/tsa');

// Opt in to a stronger imprint digest:
$tsa = new TsaClient(
    'https://timestamp.example.com/tsa',
    imprintHashAlgorithm: TsaImprintHashAlgorithm::Sha512,
);

Прежде чем отказаться от значения по умолчанию, стоит знать о двух ограничениях:

Сегодня экосистема поддерживает только SHA-256. Отпечаток, отличный от SHA-256, совместим с верификатором токенов Core, но шлюз доказательства PAdES B-T в nextpdf-server и карта дайджестов проверки в Premium в настоящее время распознают только отпечатки SHA-256. Поэтому метка времени подписи, построенная с другим дайджестом отпечатка, пока не будет доказывать B-T в этих компонентах. Сохраняйте значение по умолчанию, если только не известно, что каждый потребитель ваших меток времени принимает выбранный вами дайджест.
Предварительно вычисленные дайджесты должны соответствовать алгоритму. getDocumentTimestamp() принимает уже вычисленный хеш документа; он завершается отказом по принципу fail-closed, до какого-либо сетевого запроса, когда длина этого хеша не соответствует настроенному алгоритму отпечатка, вместо того чтобы отправлять несоответствующий запрос.

Пути перехода

Для всего, что выходит за рамки разработки или внутреннего использования, замените службу по умолчанию одним из двух более надёжных вариантов.

Публично доверенная TSA

Направьте URL TSA вашего адаптера на TSA, сертификат которой привязывается к публичному корню, которому ваши доверяющие стороны уже доверяют, — например, на http://timestamp.digicert.com. Распространять частный корень при этом не требуется. TSA промышленного уровня обычно заявляет соответствие политике простановки меток времени, такой как ETSI EN 319 421 §5, и следует профилю протокола RFC 3161, описанному в ETSI EN 319 422 §7; подтвердите это по опубликованной политике оператора, а не предполагайте это исходя только из публичного доверия.

Квалифицированная по eIDAS TSA

Для меток времени, которые должны обладать квалифицированной юридической силой в Европейском союзе, используйте квалифицированную службу простановки меток времени от квалифицированного поставщика доверенных услуг (QTSP), включённого в доверенный список ЕС. Квалифицированная электронная метка времени привязывает время к данным таким образом, чтобы разумным образом исключить незаметное изменение, основана на точном источнике времени, привязанном к всемирному координированному времени, и защищена усовершенствованной электронной подписью или усовершенствованной электронной печатью QTSP, либо эквивалентным методом (Regulation (EU) 910/2014, Art 42). Это самый надёжный вариант, и именно его следует выбирать, когда нормативный акт прямо называет квалифицированные метки времени.

Настройка по фреймворкам

Служба по умолчанию находится в конфигурации каждого адаптера фреймворка, а не в самом ядре движка. Ядро никогда не придумывает URL: TsaClient, который вы создаёте вручную, требует явной конечной точки и выбрасывает исключение, если она пуста. Долгосрочные уровни (B-LT и B-LTA) повторно используют ту же настроенную TSA, что и B-T.

Интеграция	Где находится служба по умолчанию	Как переопределить
Laravel	`config/nextpdf.php` -> `tsa.url`	задайте `NEXTPDF_TSA_URL` в `.env`
Symfony	конфигурация бандла `nextpdf.tsa.url`	задайте узел или привяжите его к переменной окружения
CodeIgniter	`Config\NextPdf::$tsa['url']`	переопределите через ключ окружения `nextPdf.tsa.url`
Plain core	неявной службы по умолчанию нет	создайте `TsaClient` с явным URL и усиленным клиентом PSR-18

В каждом адаптере B-B никогда не создаёт клиент TSA, поэтому подпись без метки времени не затрагивается ни одной из этих настроек.

Модель доверия и стандарты

Ценность метки времени — это цепочка доверия за ней, а не сами байты. Токен RFC 3161 лишь утверждает время; правдоподобность этого утверждения является свойством TSA, которая его подписала (RFC 3161 §2; ISO/IEC 18014-2 §7.3). Когда вы сохраняете поставляемую службу по умолчанию, вы выбираете самостоятельно размещаемый якорь частного доверия — это нормально для разработки и внутренних рабочих процессов, где каждая доверяющая сторона может установить корень PATEON, но не подходит для документов, проверяемых третьими сторонами. Для них перейдите на публично доверенную TSA или на квалифицированную по eIDAS TSA, когда требуется квалифицированная юридическая сила.

Если вы эксплуатируете службу по умолчанию самостоятельно, вы можете закрепить (pin) открытый ключ TSA в своём собственном внедрённом клиенте PSR-18. Не закрепляйте поставляемую службу по умолчанию в общем коде: смена ключа на стороне оператора тогда сразу сломает работу для всех пользователей службы по умолчанию. Доверие к метке времени — это цепочка сертификатов и корень PATEON, а не транспортное закрепление.