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

Кратко

Это углублённый справочник по поверхности безопасности NextPDF Pro: маскирование во время генерации, обнаружение ПДн в текстовом слое, сессия удалённого подписания и подписания через облачный KMS, многостороннее последовательное подписание, путь приёма CAdES и XAdES, базовый уровень PAdES B-B и поддержка подписания PAdES B-T (подпись B-B плюс одна метка времени подписи по RFC 3161 на значении подписи). Здесь приведены контракт публичного API, внешне наблюдаемое поведение и граница Enterprise B-LT/B-LTA. Это уровень поведения; внутренние пути реализации не цитируются.

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

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

Core поставляет программный подписант CMS, клиент меток времени по RFC 3161, проверку пути по RFC 5280 и проверку отзыва по OCSP и CRL. Pro добавляет описанные здесь маскирование, обнаружение ПДн, поверхность удалённого подписания и подписания через облачный KMS, а также поддержку подписания PAdES B-T (она компонует стек RFC 3161 из Core, добавляя метку времени подписи). Флаг возможности для этой поверхности — pro: развёртывание без активного права Pro не загружает эти классы, контракт подписания Core продолжает работать без изменений, а код, зависящий от контракта Core, не ломается при отсутствии права.

Установка

composer require nextpdf/pro:^3

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

Движок маскирования применяет упорядоченный список правил к тексту до записи страницы. Правило сопоставляется с шаблоном PCRE и заменяет совпадение одним из трёх способов:

• BlackBox — удаляет совпавший текст из потока содержимого и резервирует область заливки. Этот режим удаляет нижележащие текстовые объекты, как проверено тестами.
• Asterisks — заменяет каждый совпавший символ звёздочкой, сохраняя число символов.
• FixedLabel — заменяет всё совпадение настраиваемой меткой, по умолчанию [REDACTED].

Правило строится из точного литерала через MaskingRule::exactMatch (литерал экранируется как регулярное выражение) или из пользовательского шаблона PCRE через MaskingRule::regex. MaskingConfig хранит упорядоченный список правил, режим по умолчанию и цвет заливки. MaskingConfig::fromArray разбирает карту конфигурации и молча отбрасывает запись правила, у которой нет пригодного строкового шаблона, вместо того чтобы провалить весь импорт.

Поверхность ПДн извлекает текстовый слой PDF, затем применяет встроенные шаблоны для адресов электронной почты, телефонных номеров, номеров социального страхования США и номеров кредитных карт. Она возвращает структурированный результат: булево значение того, было ли найдено хоть одно совпадение, число совпадений, маскированное представление текста и список просканированных типов. Вызывающая сторона может ограничить сканирование подмножеством из четырёх типов. Поверхность не переписывает отрисованные глифы страницы; просканированная страница без текстового слоя не даёт совпадений. Считайте результат обнаружением шаблонов в текстовом слое для настроенных типов, а не полным удалением персональных данных и не заявлением о соответствии нормативным требованиям.

Сессия подписания двухфазная. RemoteSigningSession::create открывает сессию. prepare вычисляет дайджест документа по двум областям ByteRange, затем строит подписанные атрибуты CMS. complete вызывает стратегию и встраивает результат; suspend сериализует сессию, чтобы рабочий процесс мог позже возобновить её через resume и completeWithRawSignature. Сессия собирает CMS SignedData и хранит её в DER-кодировке в записи Contents словаря подписи — ISO 32000-2 §12.8.1. Когда передаётся разбираемый сертификат X.509, сессия эмитирует полный обязательный набор подписанных атрибутов PAdES B-B: content-type, message-digest, signing-time, signing-certificate-v2 и атрибут защиты алгоритма — RFC 5652 §5.3 и RFC 5652 §5. Проверяющая сторона повторно вычисляет дайджест содержимого и сравнивает его с атрибутом message-digest; сравнение должно совпасть, чтобы подпись была действительной — RFC 5652 §5.4.

Когда настроенный уровень PAdES — B-T (RemoteSigningConfig::default->withLevel(SignatureLevel::PAdES_B_T) или через SequentialSigner::withTimestamping) и подключён поставщик меток времени, сессия дополнительно встраивает ровно одну метку времени подписи signature-time-stamp по RFC 3161 как неподписанный атрибут CMS в первом SignerInfo. signature-time-stamp — это неподписанный атрибут, несущий один токен метки времени, вычисленный на значении цифровой подписи для подписанта — ETSI EN 319 122-1 §5.3; его MessageImprint — это хеш значения поля подписи SignerInfo с исключёнными тегом и длиной ASN.1 — ETSI EN 319 122-1 §5.3 и RFC 3161 Appendix A (OID id-aa-timeStampToken = 1.2.840.113549.1.9.16.2.14). Поскольку метка времени — неподписанный атрибут, подписанные атрибуты B-B, message-digest, значение подписи SignerInfo и /ByteRange PDF побайтово идентичны выводу B-B; растёт только CMS на величину неподписанного атрибута, а зарезервированное пространство /Contents для B-T увеличивается так, чтобы он поместился. Токен запрашивается у настроенного поставщика меток времени (клиент RFC 3161 из Core по умолчанию или поставщик, заданный вызывающей стороной). На пути поставщика по умолчанию дайджест отпечатка — SHA-256; устаревшая форма ESSCertID v1, привязанная к SHA-1, отклоняется, а требуется ESSCertIDv2 — RFC 5816 §1. Сбой TSA, отклонённый запрос, неверный nonce или эхо message-imprint, некорректный токен или токен с неподдерживаемым алгоритмом, а также токен, не прошедший криптографическую проверку, проявляются как типизированное исключение PadesBt с сохранением исходного исключения Core в качестве предыдущего. NextPDF Pro реализует поддержку подписания PAdES B-T согласно ETSI EN 319 122-1 §5.3, RFC 3161, RFC 5652 и RFC 5816 и проверена на фикстурах; она не утверждает независимую сертификацию ETSI EN 319 142-1 и не утверждает правовую действительность документа.

SequentialSigner координирует многостороннее подписание. Каждый подписант — это отдельная ревизия инкрементального обновления. Первым подписантом может быть сертифицирующая подпись с ограничением DocMDP, заданным через certifyFirst. PadesWrapper принимает существующую подпись: fromCades встраивает структуру CMS напрямую, fromXades разбирает документ XAdES и повторно использует его основной материал подписи, а detect автоматически выбирает по формату. Путь XAdES повторно использует сертификат, цепочку, значение подписи и алгоритм; он не переносит квалифицирующие свойства XAdES.

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

composer require nextpdf/pro:^3

Тип	Вид	Роль	Стабильность	С версии
RemoteSigningSession	class	Двухфазная сессия удалённого или асинхронного подписания	stable	1.9.0
RemoteSigningConfig	class	Неизменяемая конфигурация сессии, включая уровень PAdES и алгоритм	stable	1.9.0
SequentialSigner	class	Многостороннее последовательное подписание с поддержкой DocMDP	stable	1.9.0
SequentialSigningResult	class	Результат последовательного прогона: байты PDF, цепочка, число, полнота	stable	1.9.0
SigningStrategy	interface	Контракт механизма подписания, вызываемый сессией	stable	1.9.0
PadesWrapper	class	Оборачивает существующую подпись CAdES или XAdES для встраивания PAdES	stable	1.9.0
KmsSignerInterface	interface (SPI)	Контракт стороннего драйвера HSM и KMS; расширяет контракт подписанта HSM из Core	stable	2.1.0
SignatureAlgorithm	enum	OID алгоритмов подписи Pro и имена дайджестов	stable	2.1.0
GenerationTimeMasker	class	Маскирование по правилам, применяемое до записи страницы	stable	1.9.0
MaskingConfig	class	Неизменяемая конфигурация маскирования	stable	1.9.0
MaskingRule	class	Одно правило маскирования (литерал или PCRE)	stable	1.9.0
MaskingMode	enum	BlackBox, Asterisks, FixedLabel	stable	1.9.0

Контракт SigningStrategy

Стратегия работает с подписанными атрибутами в DER-кодировке и возвращает сырые байты подписи. CMS SignedData собирает сессия, а не стратегия. Стратегия предоставляет DER сертификата подписанта, DER цепочки, упорядоченной от листа к корню, OID алгоритма подписи, имя алгоритма дайджеста и флаг isAsync, отмечающий стратегию, чья сессия может быть сериализована и возобновлена.

SPI KmsSignerInterface

KmsSignerInterface расширяет контракт подписанта HSM из Core. Он добавляет стабильный providerId для поиска в реестре, метод signWithVersion с явным параметром версии ключа для каждого вызова, а также supportsAlgorithm и supportedAlgorithms, чтобы вызывающая сторона определяла совместимость алгоритмов до вызова подписания. Зарезервированные встроенные идентификаторы поставщиков — aws-kms, azure-keyvault, gcp-kms, pkcs11, openssl-cli и openssl-engine. Сторонний драйвер должен снабдить свой идентификатор пространством имён, чтобы избежать коллизии. Семантика версии ключа по умолчанию различается у разных поставщиков: поставщик с разрешением псевдонимов разрешает активный ключ по псевдониму, когда версия — null; поставщик, выбирающий последнюю включённую версию, делает это через свой транспорт; поставщик без серверного понятия активной версии должен использовать версию, закреплённую в его конфигурации, и должен возбуждать ошибку управления ключами, когда ни вызов, ни конфигурация не закрепляют версию. Непустая версия закрепляет эту версию, и поставщик должен возбуждать ошибку управления ключами, когда версия неизвестна, отключена или отозвана.

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

• Сформированная подпись — это не проверенная подпись. Проверка пути выполняется у проверяющей стороны с её якорями доверия и проверками базовых ограничений — RFC 5280 §6.1. Сторона, формирующая подпись, не может утверждать результат.
• У сессии есть устаревший резерв из трёх атрибутов для байтов синтетического сертификата не-X.509. Продакшен-стратегии всегда поставляют реальный DER X.509, поэтому полный набор атрибутов B-B — это продакшен-путь. Резерв существует только для исторической тестовой поверхности механики DER.
• Структура CMS должна помещаться в зарезервированное пространство Contents. SignedData B-B с полной цепочкой сертификатов имеет размер; сессия возбуждает ошибку переполнения, когда собранная CMS превышает зарезервированное шестнадцатеричное пространство. Соответственно размеряйте зарезервированное пространство. Для B-T встроенный токен RFC 3161 (доминируемый цепочкой сертификатов TSA) увеличивает CMS; зарезервированное пространство B-T увеличивается автоматически, а недостаточно большое настроенное пространство проваливается закрыто с типизированной ошибкой конфигурации, а не усекается.
• MaskingConfig::fromArray отбрасывает запись без пригодного строкового шаблона вместо провала импорта. Проверяйте источник конфигурации, если молчаливый отброс недопустим.
• Режим black-box маскирования эмитирует пустую замену для совпавшего фрагмента и удаляет нижележащий текст. Правило, которое не совпало со значением, не маскирует его; движок не утверждает, что всё чувствительное содержимое найдено.
• B-T требует подключённого поставщика меток времени. На пути поставщика RFC 3161 из Core по умолчанию дайджест отпечатка — SHA-256; отпечаток не-SHA-256 на этом пути отклоняется типизированной ошибкой конфигурации, а не молча понижается, а поставленный вызывающей стороной пользовательский поставщик может правомерно использовать другой одобренный дайджест. serialNumber метки времени уникален для токена от данного органа меток времени (Time-Stamping Authority), а genTime — это момент UTC создания токена — RFC 3161 §2.4.1, §2.4.2. Материал долгосрочной проверки B-LT/B-LTA остаётся вопросом границы Enterprise; Pro не формирует ни DSS, ни VRI, ни метку времени документа.
• OCSP unknown — это не good, а свежесть статуса ограничена thisUpdate и nextUpdate — RFC 6960 §2.2, §4.2.

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

Pro выбирает алгоритм из настроенного алгоритма подписи и стратегии. При настройке против KMS или HSM, валидированного по FIPS, криптографическая операция выполняется в этой валидированной границе, а набор алгоритмов — тот, что разрешает эта граница. NextPDF Pro выполняет структурную сборку CMS и вычисление дайджеста; он не является криптографическим модулем, валидированным по FIPS, и не делает заявления о сертификации FIPS. Развёртывание, требующее режима FIPS, должно настроить KMS или HSM, валидированный по FIPS, а профиль криптополитики FIPS 140-3 — это возможность Enterprise.

Положение по экспортному контролю

Этот модуль касается криптографической функциональности; относитесь к нему как к чувствительному с точки зрения безопасности в своём собственном обзоре.

Граница Enterprise

NextPDF Pro формирует базовый уровень B-B и уровень B-T. Для B-B сессия собирает CMS SignedData с набором подписанных атрибутов B-B и не применяет метку времени. Для B-T она добавляет ровно одну метку времени подписи signature-time-stamp по RFC 3161 как неподписанный атрибут CMS, вычисленный на значении цифровой подписи для подписанта — ETSI EN 319 122-1 §5.3. NextPDF Pro реализует это согласно ETSI EN 319 122-1 §5.3, RFC 3161, RFC 5652 и RFC 5816 и проверена на фикстурах; она не утверждает независимой сертификации, соответствия или комплаенса ETSI EN 319 142-1 и не утверждает правовую действительность документа.

Уровни B-LT и B-LTA — это возможности Enterprise и не формируются Pro. B-LT и B-LTA добавляют Document Security Store и метки времени документа для долгосрочной архивной проверки — ETSI EN 319 142-2 §5.5. Обработчик подписи, формирующий эти уровни, поддерживает записи DSS и метки времени документа — ETSI EN 319 142-2 §6.3.3.3. RemoteSigningConfig из Pro может нести уровень выше B-T (B-LT или B-LTA), который запрашивает Document Security Store, но Pro не поставляет этот формирователь и не действует по нему; такой уровень — это значение с упреждающим объявлением. Поток подписания Core разрешает долгосрочный формирователь во время выполнения через контракт Core, и этот формирователь поставляется в пакете nextpdf/enterprise. В развёртывании только с Pro запрос B-LT или B-LTA проваливается закрыто с сообщением, называющим отсутствующий компонент Enterprise. Pro не формирует ни DSS, ни словаря VRI, ни метки времени документа, ни архивного цикла и не делает заявления о долгосрочной проверке (LTV). Аппаратное хранение ключей через PKCS#11 и профиль криптополитики FIPS 140-3 также являются возможностями Enterprise. Эта страница не документирует реализацию долгосрочной проверки в Enterprise; она указывает только границу и публичное имя пакета.

Уровень PAdES	Добавляет	Редакция-формирователь
B-B	Подпись CMS с подписанными атрибутами	Core, Pro
B-T	Один неподписанный атрибут signature-time-stamp по RFC 3161 на значении подписи	Core, Pro
B-LT	Document Security Store с материалом проверки	Enterprise (nextpdf/enterprise)
B-LTA	Метки времени документа для архивной действительности	Enterprise (nextpdf/enterprise)

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

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

Резервный режим Core

Развёртывание без права Pro сохраняет контракт подписания Core. Код, зависящий от контракта SignerInterface из Core, продолжает подписывать программным подписантом CMS на базовом уровне B-B. Маскирование, обнаружение ПДн и стратегии удалённого подписания и подписания через облачный KMS отсутствуют без пакета Pro, и вызов в эти типы — это жёсткая ошибка зависимости, а не молчаливый no-op.

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

Поверхности маскирования и ПДн выполняются в процессе. Содержимое документа не покидает хост для маскирования или обнаружения ПДн. Стратегия облачного KMS отправляет поставщику для операции подписания дайджест подписанных атрибутов, а не сам документ. Обнаружение ПДн выполняется сопоставлением шаблонов для настроенных типов и удаляет нижележащие текстовые объекты для режима black-box, как проверено тестами. Это не гарантия полного удаления персональных данных и не заявление о соответствии нормативным требованиям.

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

Библиотека возбуждает типизированные исключения со структурными сообщениями. Она не пишет содержимое документа или обнаруженные значения ПДн в сообщения исключений или журналы. Развёртывание, ведущее журналы вокруг пути подписания, должно журналировать структурные поля, а не байты документа.

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

Утверждение	Стандарт	Пункт
Подпись CMS хранится в DER-кодировке в записи Contents словаря подписи.	ISO 32000-2	§12.8.1
Процесс вычисления дайджеста сообщения; подписанные атрибуты несут content-type и message-digest.	RFC 5652	§5.4
Проверяющая сторона не должна полагаться на дайджесты, вычисленные отправителем; она независимо пересчитывает и сравнивает (процесс проверки подписи).	RFC 5652	§5.6
SignerInfo несёт идентификатор алгоритма дайджеста и блок подписанных атрибутов.	RFC 5652	§5
Запрос метки времени возвращает структуру TSTInfo.	RFC 3161	§2.4.1
serialNumber метки времени уникален для токена от данного TSA.	RFC 3161	§2.4.2
genTime метки времени — это момент UTC создания токена.	RFC 3161	§2.4.2
signature-time-stamp PAdES B-T — это неподписанный атрибут, несущий один токен метки времени, вычисленный на значении цифровой подписи для подписанта (Pro формирует B-T).	ETSI EN 319 122-1	§5.3
Отпечаток signature-time-stamp — это хеш значения поля подписи SignerInfo с исключёнными тегом и длиной ASN.1.	ETSI EN 319 122-1	§5.3
Токен signature-time-stamp использует OID id-aa-timeStampToken; его MessageImprint — это хеш значения поля подписи SignerInfo.	RFC 3161	Appendix A
На стороне проверки NextPDF привязывает MessageImprint токена signature-time-stamp к значению подписи SignerInfo и проваливается закрыто при несовпадении, отсутствующем/дублированном токене или отпечатке SHA-1 (строгая проверка, не сертификация).	RFC 3161	Appendix A
ESSCertIDv2 заменяет устаревший ESSCertID, привязанный к SHA-1; строгий путь B-T требует ESSCertIDv2.	RFC 5816	§1
Проверка пути сертификации проверяет базовые ограничения и входные данные пути к якорю доверия.	RFC 5280	§6.1
OCSP сообщает certStatus как good, revoked или unknown.	RFC 6960	§2.2
Свежесть статуса OCSP ограничена thisUpdate и nextUpdate.	RFC 6960	§4.2
B-LT и B-LTA добавляют Document Security Store и метки времени документа для долгосрочной проверки (граница Enterprise).	ETSI EN 319 142-2	§5.5
Обработчик подписи, формирующий долгосрочные уровни, поддерживает записи DSS и метки времени документа (граница Enterprise).	ETSI EN 319 142-2	§6.3.3.3

Все пункты пересказаны. NextPDF не воспроизводит нормативный текст. Авторитетные формулировки см. в опубликованных стандартах. NextPDF Pro реализует поддержку подписания PAdES B-T согласно ETSI EN 319 122-1 §5.3 (signature-time-stamp), RFC 3161, RFC 5652 и RFC 5816 и проверена на фикстурах. ETSI EN 319 142-1 (часть о базовых уровнях PAdES) находится за пределами цитируемого набора свидетельств; поэтому NextPDF Pro не утверждает независимой сертификации, соответствия или комплаенса ETSI EN 319 142-1 и не утверждает правовую действительность документа. Эта страница указывает сформированную структуру, стандарты, которые реализует поддержка B-T, и границу Enterprise B-LT/B-LTA, а не сертифицированный уровень соответствия.

См. также

• Подписание в Core — подписант CMS, метка времени RFC 3161, проверка пути RFC 5280, OCSP и CRL.
• Карта пунктов PAdES — B-B, B-T, B-LT, B-LTA по редакциям.
• Security (обзор возможности) — публичная страница возможности безопасности Pro.
• CMS · PAdES · Метка времени RFC 3161 · KMS · DSS — термины глоссария.