Использование цифровой подписи PAdES в NextPDF Connect (Pro)

Кратко

Применяйте базовую цифровую подпись PDF Advanced Electronic Signatures (PAdES) к PDF через NextPDF Connect. Используйте sign_pdf: он повторно сверен с поставщиком инструментов Pro, который регистрирует new SignPdfTool() с именем протокола sign_pdf. sign_pdf — это инструмент уровня Pro. При запуске сервер проверяет его через class_exists() и регистрирует только тогда, когда установлен пакет Pro.

По умолчанию инструмент создаёт PAdES B-B. Он может создавать PAdES B-T (B-B плюс одна RFC 3161 signature-time-stamp) только тогда, когда хост подключил поставщика меток времени к инструменту; запрос не может указывать службу меток времени (Time Stamp Authority, TSA). Долгосрочные уровни (B-LT, B-LTA) и их материалы проверки (DSS, VRI, LTV) не входят в этот инструмент и здесь не рассматриваются.

Оговорка U-1. NextPDF не заявляет о самостоятельной сертификации PAdES B-T по ETSI EN 319 142-1. EN 319 142-1 не входит в корпус проверки. Требование B-T signature-time-stamp проверялось по ETSI EN 319 122-1 §5.3 (основа CAdES, которую EN 319 142-1/-2 импортируют по ссылке) вместе с RFC 3161, RFC 5652, RFC 5816 и ISO 32000-2 §12.8. Поддержка профиля B-T не подтверждает соответствие или юридическую силу; это определяет независимый валидатор.

Установка

composer require nextpdf/server
composer require nextpdf/pro

Привяжите транспорт, затем через diagnostic.capabilities убедитесь, что sign_pdf доступен. Для B-T хост должен создать инструмент с поставщиком меток времени. Без него запрос pades_b_t: true завершается типизированной ошибкой, а не молчаливым понижением уровня.

Концептуальный обзор

sign_pdf вычисляет дайджест по диапазону байтов файла, исключая местозаполнитель значения подписи (ISO 32000-2 §12.8.1). Затем он записывает структуру Cryptographic Message Syntax (CMS) SignedData в кодировке Distinguished Encoding Rules (DER) в словарь подписи Contents (ISO 32000-2 §12.8.1). Поддерживаемые алгоритмы — RSA-SHA256 (по умолчанию), RSA + SHA-3 (256/384/512) и Ed25519. Для транспортов без сквозной конфиденциальности вы можете обернуть входящую полезную нагрузку private_key в необязательный конверт AES-GCM.

Переход на B-T. При pades_b_t: true и подключённом хостом поставщике меток времени подпись повышается до PAdES B-T: хеш по диапазону байтов отправляется в TSA, а TimeStampToken встраивается (ISO 32000-2 §12.8.5). B-T — это ровно B-B плюс одна RFC 3161 signature-time-stamp, передаваемая как неподписанный атрибут в CMS SignerInfo (RFC 5652 §5.3). Неподписанные атрибуты не охватываются подписью, поэтому подписанный дайджест B-B и его достоверность остаются неизменными (RFC 5652 §5.3). Значением атрибута является SignatureTimeStampToken (ETSI EN 319 122-1 §5.3). B-T не добавляет ни словаря Document Security Store (DSS), ни Validation Related Information (VRI), ни материалов проверки, ни цикла архивных меток времени. Эти добавления относятся к B-LT/B-LTA уровня Enterprise и выходят за рамки этого инструмента.

Оговорка U-1 (повторяется при заявлении B-T). Поддержка B-T здесь не является сертификацией соответствия EN 319 142-1 и не подтверждает юридическую силу; решение принимает независимый валидатор. EN 319 142-1 не входит в корпус проверки. B-T основан на ETSI EN 319 122-1 §5.3, RFC 3161, RFC 5652, RFC 5816 и ISO 32000-2 §12.8.

На схеме ниже показан управляемый хостом путь к TSA (запрос не может указывать TSA) и ветвь B-T с явным отказом (без молчаливого понижения уровня).

Diagram

Поверхность API

Инструмент	Уровень	Роль	Уровень риска
create_pdf, add_text	Core (базовый)	Создание содержимого	Безопасно / С осторожностью
sign_pdf	Pro (профессиональный)	Применение PAdES B-B (или управляемого хостом B-T)	Требуется подтверждение
output_pdf	Core (базовый)	Отрисовка и возврат PDF	Требуется подтверждение / Проверка (base64)

Имена инструментов совпадают с именами протоколов в реестре. Каталог инструментов — эталонный каталог. Доступные инструменты зависят от установленного уровня, и в Pro нет инструментов для долгосрочных уровней.

Пример кода — быстрый старт

1. create_pdf → создайте содержимое с помощью add_text.
2. sign_pdf с certificate (PEM), private_key (PKCS#8 PEM), необязательными signer_name, reason и algorithm. Для B-B опустите pades_b_t (или задайте ему false).
3. output_pdf.

Инструмент возвращает такой конверт результата:

{
  "pdf": "<base64 of the signed PDF>",
  "signature_count": 1,
  "is_complete": true,
  "algorithm": "RSA_SHA256",
  "oid": "<algorithm OID>",
  "digest": "<digest algorithm>",
  "level": "PAdES-B-B",
  "timestamped": false
}

Для управляемой хостом подписи B-T передайте pades_b_t: true; level становится "PAdES-B-T", а timestamped — true.

Пример кода — продакшн

Выполняйте подписание последней операцией с содержимым. Любая add_text/add_image после sign_pdf делает подпись недействительной. На неконфиденциальном транспорте оберните private_key в конверт AES-GCM transport_encryption (12-байтовый одноразовый код; ключ 16/24/32 байта). Убедитесь, что level в результате соответствует вашему запросу. Запрос pades_b_t: true к инструменту без поставщика завершается явной ошибкой. Обработайте эту ошибку и не повторяйте попытку как B-B молча.

Граничные случаи и подводные камни

• Несоответствие сертификата и ключа. Инструмент отклоняет запрос с понятной ошибкой; закрытый ключ должен соответствовать открытому ключу сертификата.
• Некорректный PEM / просроченный сертификат. Инструмент отклоняет запрос; по умолчанию он не подписывает с нечитаемым или просроченным сертификатом.
• Содержимое после подписания. Инструмент отклоняет запрос — подписывайте последним.
• Запрошен B-T, поставщика нет. Инструмент возвращает типизированную ошибку: подпись не создаётся и не понижается молчаливо до B-B.
• Самоподписанный сертификат. Подпись применяется, но программы для чтения показывают неизвестный уровень доверия. Это ожидаемо, а не дефект инструмента.
• Pro отсутствует. Если установлен только Core, сервер не регистрирует sign_pdf.

Производительность

Подписание добавляет сборку CMS и, для B-T, один цикл обращения к TSA; бюджет учитывает и то, и другое. Профиль — semantic: токен RFC 3161 по своей природе невоспроизводим, а дайджест по диапазону байтов §12.8.1 исключает значение подписи. Используйте только сравнение AST и метаданных подписи.

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

Подпись обеспечивает целостность и аутентификацию относительно ключа подписания. Сама по себе она не делает документ “защищённым” или “юридически действительным” и не гарантирует неотказуемость. Эти результаты зависят от сертификата, его якоря доверия, хранения ключа и политики проверяющей стороны — всё это вне данного инструмента. Шифрование полезной нагрузки ключа конвертом AES-GCM защищает конфиденциальность при передаче, а не целостность. Относитесь к закрытому ключу как к секрету и предпочитайте конверт transport-encryption на любом неконфиденциальном канале.

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

Утверждение	Спецификация	Раздел	Идентификатор ссылки (reference_id)
Дайджест по диапазону байтов охватывает файл и исключает значение подписи.	ISO 32000-2	§12.8.1
Contents содержит CMS SignedData в кодировке DER.	ISO 32000-2	§12.8.1
Для метки времени хеш по диапазону байтов отправляется в TSA, а токен помещается в Contents.	ISO 32000-2	§12.8.5
Метка времени B-T является неподписанным атрибутом в SignerInfo.	RFC 5652	§5.3
Неподписанные атрибуты не изменяют подписанный B-B digest/validity.	RFC 5652	§5.3
Значением signature-time-stamp является SignatureTimeStampToken.	ETSI EN 319 122-1	§5.3

NextPDF создаёт структуру подписи. NextPDF не заявляет, что какая-либо итоговая подпись соответствует требованиям или юридически действительна; решение принимает независимый валидатор. Этот инструмент не создаёт B-LT/B-LTA.

Коммерческий контекст

sign_pdf — это инструмент уровня Pro. Сервер регистрирует его только тогда, когда пакет Pro доступен при запуске сервера. Долгосрочные уровни PAdES (B-LT, B-LTA) и их материалы проверки (DSS, VRI, LTV) доступны только в Enterprise и не предоставляются ни этим инструментом, ни этим рецептом.

Резидентность данных и меры по защите ПДн

Сертификат и закрытый ключ передаются в запросе. Используйте конверт AES-GCM transport_encryption на любом канале без сквозной конфиденциальности. Подписанный PDF и идентификационные данные подписавшего (signer_name, reason) являются содержимым документа, поэтому сохраняйте их в пределах вашей границы резидентности данных. За резидентность на уровне развёртывания отвечает интегратор.

Безопасная телеметрия и очистка журналов

Никогда не записывайте в журнал полезную нагрузку private_key, key/nonce AES-GCM или токен подтверждения. Записывайте в журнал алгоритм, итоговый level и signature_count, а не ключевой материал. Инструмент не возвращает байты ключа в результате.

Модель угроз

Рассматриваемые угрозы: раскрытие ключа при передаче (смягчается конвертом AES-GCM); указание вызывающей стороной MCP произвольной конечной точки меток времени (предотвращается тем, что поставщик TSA подключается хостом, а не настраивается через запрос); и подделка после подписания (дайджест по диапазону байтов обнаруживает изменение). Модель угроз документирует рассматриваемые угрозы и меры их смягчения; она не утверждает отсутствие уязвимостей.

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

Выбор алгоритма (RSA-SHA256, RSA + SHA-3, Ed25519) управляется запросом. Криптографические примитивы предоставляет OpenSSL хоста. В развёртывании с ограничениями FIPS ограничьте алгоритм на уровне политики и полагайтесь на проверенный модуль хоста. Сам этот инструмент не заявляет о валидации по Federal Information Processing Standards (FIPS).

Доступность транспортов

Транспорт	Доступно	Примечания
MCP (stdio) — стандартный ввод-вывод	Да (Pro)	Используйте конверт ключа AES-GCM на stdio.
REST	Да (Pro)	Предпочтительно TLS плюс конверт ключа.
gRPC	Да (Pro)	Предпочтительно TLS плюс конверт ключа.

Уровень риска HITL

sign_pdf относится к категории “Требуется подтверждение”, потому что это разрушающая и необратимая операция; инструмент объявляет подсказку о разрушающем характере. Подтверждающий шлюз применяется так же, как для любого инструмента категории “Требуется подтверждение”. output_pdf при записи в файл также относится к категории “Требуется подтверждение”; режим base64 — это “Проверка” (уровни риска HITL).

JSON-конверт подтверждающего шлюза

sign_pdf без действительного токена возвращает конверт запроса-вызова:

{
  "allowed": false,
  "challenge": "⚠️ CONFIRMATION REQUIRED\n\nOperation: sign_pdf\nDescription: <tool description>\n\nTo proceed, call sign_pdf again with parameter _confirmation_token: \"confirm_<single-use-hex>\"\nExpires in 300 seconds.",
  "token": "confirm_<single-use-hex>"
}

Вызовите инструмент снова, передав _confirmation_token, равный токену → { "allowed": true }. Полный процесс: output-approval.

См. также

• Извлечение текстового содержимого
• Проверка доступности
• Уровни риска HITL
• Каталог инструментов