Accelerator — GPU-сайдкар и фабрика провайдеров KMS

Кратко

NextPDF Enterprise добавляет две возможности ускорения: GPU-сайдкар для встраивания текста с резервным выполнением на CPU и фабрику провайдеров KMS, которая поставляет метаданные ключей шифрования данных уровня коллекции и их ротацию. На этой странице описаны поведение, границы и подход к хранению ключей.

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

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

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

GPU-сайдкар ускоряет встраивание текста в векторы. Пакет Enterprise отправляет текст в отдельный процесс-сайдкар по локальному запросу HTTP. Сайдкар запускает модель встраивания на GPU, когда тот доступен. Когда GPU недоступен, сайдкар выполняет ту же модель на CPU и сообщает, что работал в режиме с пониженной производительностью. Форма вектора в обоих случаях одинакова. Модель встраивания загружается при первом запросе, поэтому первый запрос медленнее последующих. Сайдкар необязателен; предоставляется проверка доступности, а отсутствие сайдкара вызывает типизированное исключение, а не тихий сбой.

Фабрика провайдеров KMS выбирает провайдера управления ключами из конфигурации. Фабрика читает переменную окружения, чтобы выбрать провайдера. Провайдер по умолчанию локально выводит ключ шифрования данных для конкретной коллекции с помощью HKDF-SHA256 из настроенного мастер-ключа, используя идентификатор коллекции как разделитель домена. Локальный провайдер не обращается ни к какой внешней службе; вывод ключа детерминирован и выполняется внутри процесса. Фабрика также принимает явную форму конфигурации для локального провайдера. Облачные провайдеры — AWS KMS, GCP Cloud KMS, Azure Key Vault и HashiCorp Vault Transit — это распознаваемые имена провайдеров; выбор одного из них без установленной соответствующей интеграции вызывает типизированную ошибку конфигурации, которая называет недостающую зависимость.

Провайдер возвращает метаданные ключа, а не его байты. Метаданные фиксируют идентификатор ключа, монотонно возрастающую версию ключа, имя алгоритма шифрования и имя провайдера. Вызов ротации увеличивает версию ключа и возвращает новые метаданные. Вызывающая сторона отвечает за повторное шифрование данных коллекции новой версией ключа после ротации. Жизненный цикл версий и ротации ключей следует NIST SP 800-57 Part 1 Rev.5 §4.

Почему это работает именно так

Встраивание выполняется в отдельном процессе GPU-сайдкара, а не внутри PHP-запроса. Загрузка GPU-модели затратна, поэтому сайдкар загружает модель один раз и распределяет эту стоимость на множество запросов. Когда GPU отсутствует, сайдкар выполняет ту же модель на CPU и сообщает о режиме с пониженной производительностью. Пропускная способность может снизиться, но корректность — нет: форма вектора в любом случае одинакова. Сайдкар остаётся необязательным; проверка доступности и типизированное исключение при отсутствии сайдкара делают ускорение осознанным выбором, а не скрытой зависимостью. Такое разделение позволяет масштабировать встраивание больших объёмов на выделенном оборудовании, пока конвейер документов остаётся обычным вызовом PHP.

Проектный контекст: Генерация документов больших объёмов.

Программный интерфейс

Публичная поверхность	Вид	Назначение	Стабильность	С версии
KMS provider factory	class	Построить провайдера KMS из окружения или явной конфигурации	stable	2.1.0
KMS provider	interface	Получить метаданные ключа, выполнить ротацию ключа и сообщить имя провайдера	stable	2.1.0
Local KMS provider	class (implements the provider interface)	Локальный вывод ключа HKDF-SHA256; не обращается ни к какой внешней службе	stable	2.1.0
Encryption-key result	value object	Неизменяемые метаданные ключа: идентификатор ключа, версия, алгоритм, провайдер — без байтов ключа	stable	2.1.0
GPU embedding service	class (implements the Core embedding-service interface)	Встраивание текста на GPU-сайдкаре с резервным выполнением на CPU	stable	2.1.0

Фабрика провайдеров предоставляет точку входа «из окружения» и явную точку входа «создать». Значение конфигурации мастер-ключа помечено как конфиденциальное в локальном провайдере. Авторитетный контракт параметров и типов — это опубликованный справочник API пакета nextpdf/enterprise; считайте контрактом именно этот справочник, а не данную страницу.

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

composer require nextpdf/core
composer require nextpdf/enterprise:^3

Build the local KMS provider and read key metadata

use NextPDF\Enterprise\Accelerator\KmsProviderFactory;

// Selects the provider from environment configuration; defaults to the
// local HKDF-based provider. Supply the root key through your secret
// manager, never from source or logs.
$provider = KmsProviderFactory::fromEnvironment();

$key = $provider->getEncryptionKey('collection-1');
// $key is metadata only: key id, version, algorithm, provider name.

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

Rotate a collection key, then re-encrypt collection data

use NextPDF\Enterprise\Accelerator\KmsProviderFactory;

$provider = KmsProviderFactory::fromEnvironment();

$rotated = $provider->rotateKey('collection-1');
// The version advanced. Re-encrypt the collection's data files with the
// new key version. The provider returns metadata only; it never returns
// raw key bytes.

Имена переменных окружения, ключи явной конфигурации и типы исключений описаны в подробном справочнике Accelerator.

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

• Локальный провайдер KMS требует мастер-ключ в шестнадцатеричной кодировке длиной не менее 32 байт. Более короткое или не-шестнадцатеричное значение вызывает типизированное исключение аргумента при конструировании.
• Выбор имени облачного провайдера без установленной соответствующей интеграции вызывает типизированную ошибку конфигурации, которая называет недостающую зависимость.
• Неизвестное имя провайдера вызывает типизированную ошибку, которая перечисляет поддерживаемые имена.
• GPU-сайдкар сообщает о режиме с пониженной производительностью, когда переходит на CPU. Проверяйте это поле, если зависите от пропускной способности GPU.
• Модель встраивания загружается при первом запросе; задавайте тайм-аут первого запроса соответственно.

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

Локальный вывод ключа — это операция HKDF с постоянной стоимостью. Она не обращается ни к какой внешней службе. Запрос встраивания на GPU добавляет один локальный круговой обмен с сайдкаром плюс время вывода модели. Первый запрос дополнительно оплачивает разовую стоимость загрузки модели. Резервное выполнение на CPU корректно, но медленнее пути GPU для одной и той же пачки.

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

• Провайдер KMS возвращает метаданные ключа, а не его байты. Объект-значение результата ключа шифрования никогда не несёт сам ключевой материал.
• Мастер-ключ локального провайдера — это конфиденциальный параметр конструктора. Он не логируется и не сериализуется.
• Локальный провайдер не обращается ни к какой внешней службе. Вывод детерминирован и выполняется внутри процесса.
• Использование AES-GCM требует уникального вектора инициализации на каждый ключ, согласно NIST SP 800-38D §5.

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

Локальный провайдер KMS работает внутри процесса и не обращается ни к какой внешней службе; для локального вывода ключа ни ключевой материал, ни содержимое документов не покидают хост. GPU-сайдкар получает текст для встраивания по локальному запросу; он не получает постороннее содержимое документов. Облачный провайдер KMS, если настроен, обращается к выбранному вами облачному провайдеру; ознакомьтесь с его политикой резидентности данных применительно к вашей юрисдикции.

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

Мастер-ключ локального провайдера — это конфиденциальный параметр конструктора, исключённый из журналов и сериализации. Не добавляйте мастер-ключ, выведенные ключи или учётные данные провайдера в собственные журналы приложения. Считайте весь ключевой материал секретом в своей политике журналирования и трассировки.

Модель угроз

Провайдер возвращает метаданные, а не байты ключа, поэтому утечка метаданных не раскрывает ключевой материал. Безопасность локального провайдера зависит от секретности настроенного мастер-ключа. Безопасность облачного провайдера зависит от этого провайдера и вашей конфигурации. Защита ключей зависит от KMS или секрета мастер-ключа, от развёртывания и от оператора — а не только от этого программного обеспечения. См. границу развёртывания.

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

• Жизненный цикл версий и ротации ключа шифрования данных согласован с NIST SP 800-57 Part 1 Rev.5 §4.
• Ответственность за защиту ключей согласована с NIST SP 800-57 Part 1 Rev.5 §5.5.2.
• Уникальность вектора инициализации AES-GCM согласована с NIST SP 800-38D §5.

Каждый нормативный источник приведён в пересказе. Нормативный текст на этой странице не воспроизводится. Эта страница касается управления ключами.

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

Вывод ключей HKDF локального провайдера использует SHA-256. Алгоритм шифрования, записанный в метаданных ключа, — AES-256-GCM. Когда приложение работает с криптографическим провайдером, валидированным по FIPS, эти примитивы выполняются в этой валидированной границе. Сама фабрика провайдеров выбирает и конструирует провайдера; она не сертифицирует криптографическую границу.

NextPDF Enterprise не является криптографическим модулем, валидированным по FIPS, и не делает заявления о сертификации FIPS. Он работает в FIPS-совместимом режиме только тогда, когда настроен с валидированным по FIPS криптографическим провайдером или валидированным по FIPS KMS.

Граница редакции

GPU-сайдкар встраивания и фабрика провайдеров KMS поставляются только в пакете nextpdf/enterprise. NextPDF Pro предоставляет интеграцию KMS для стратегий подписания (AWS KMS, GCP Cloud KMS, Azure Key Vault), но не предоставляет фабрику провайдеров KMS уровня Enterprise или GPU-сайдкар встраивания. Внутренний транспорт сайдкара и внутренние классы конвейера встраивания находятся вне области публичного интерфейса и здесь не воспроизводятся.

Резервный вариант Pro

NextPDF Pro предоставляет стратегии подписания через облачный KMS — KMS хранит ключ подписания, а Pro отправляет дайджест подписанных атрибутов провайдеру. Это интеграция подписания. Это не фабрика провайдеров ключей шифрования данных уровня коллекции из Enterprise и не GPU-сайдкар встраивания. См. Accelerator — NextPDF Pro для поверхности ускорения Pro.

Резервный вариант Core

У NextPDF Core нет GPU-сайдкара встраивания и нет фабрики провайдеров KMS. Встраивание и управление ключами уровня коллекции — это возможности только Enterprise.

Примечание о границе Enterprise

Транспорт GPU-сайдкара, идентификатор модели встраивания и внутренние классы конвейера описаны только на уровне поведения. Внутренний транспортный клиент, внутренние токены областей действия и внутренняя композиция конвейера находятся вне области публичного интерфейса и здесь не воспроизводятся.

Граница развёртывания

NextPDF Enterprise интегрируется с KMS или выводит ключи из настроенного секрета мастер-ключа. Он сам не хранит и не гарантирует безопасность этого секрета мастер-ключа или ключа облачного KMS. Безопасность ключей зависит от KMS или секрета мастер-ключа, от развёртывания и от оператора — а не только от NextPDF Enterprise. Оператор отвечает за подготовку мастер-ключа, хранение секретов, настройку KMS и расписание ротации. Ответственность за защиту ключей следует NIST SP 800-57 Part 1 Rev.5 §5.5.2. NextPDF Enterprise не раскрывает в этой документации потоки учётных данных KMS или внутренние детали обработки мастер-ключа.

Граница юридического соответствия

Эта страница касается управления ключами. Утверждение о режиме FIPS — это заявление о совместимости, а не сертификация и не юридическое заключение. Обращайтесь к собственным консультантам по соответствию и юристам по вопросам ваших регуляторных обязательств.

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

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

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

• Фабрика провайдеров выбирает провайдера из конфигурации и возвращает провайдера, удовлетворяющего контракту провайдера.
• Провайдер возвращает неизменяемые метаданные ключа и никогда не возвращает байты ключа.
• Вызов ротации увеличивает версию ключа и возвращает новые метаданные; вызывающая сторона повторно шифрует данные коллекции.
• GPU-сайдкар сообщает о режиме с пониженной производительностью при переходе на CPU и вызывает типизированное исключение, когда недоступен.

См. также

• Accelerator reference — NextPDF Enterprise
• Security — NextPDF Enterprise
• Intelligence — NextPDF Enterprise
• Accelerator — NextPDF Pro
• KMS · DEK · HKDF — термины глоссария.