Pro редакция

Подписание через облачный KMS (AWS KMS, Azure Key Vault, GCP KMS)

Кратко

NextPDF Pro подписывает PDF ключом, который хранится в облачной службе управления ключами (KMS). Поддерживаемые провайдеры — Amazon Web Services (AWS) KMS, Microsoft Azure Key Vault и Google Cloud Platform (GCP) Cloud KMS. Каждый провайдер реализует один контракт подписания, поэтому ваше приложение зависит от контракта, а не от класса провайдера. Провайдеру передаётся только дайджест подписанных атрибутов; для операции подписания документ никогда не покидает ваш хост. Эта страница описывает уровень поведения: что каждый провайдер отправляет и получает, как разрешаются версии ключа и где хранение ключа перестаёт быть зоной ответственности NextPDF.

Контракт расширяет контракт аппаратного и облачного подписанта из Core, поэтому стратегия облачного KMS подключается к тому же пути подписания, который использует подписант Core.

Предварительные требования указаны во вступительном блоке и повторены в разделе Предварительные требования.

Редакция и лицензирование

Стратегии подписания через облачный KMS поставляются в пакете nextpdf/pro и активируются лицензионным флагом возможности pro. NextPDF Core поставляет программный подписант CMS; NextPDF Enterprise добавляет аппаратное хранение ключей через PKCS#11. Подписание через облачный KMS — это возможность Pro, доступная также и в Enterprise, поскольку Enterprise зависит от Pro. Развёртывание без активного права Pro не загружает эти классы стратегий; контракт подписания Core продолжает работать без изменений. Сравнить редакции.

Что делает эта возможность

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

Поток подписания оставляет документ на вашем хосте:

Сессия подписания Pro вычисляет дайджест документа и формирует подписанные атрибуты CMS.
Сессия хеширует подписанные атрибуты и отправляет провайдеру только этот дайджест. Внешняя служба подписания, которая принимает переданный вызывающей стороной дайджест сообщения и возвращает подпись, — устоявшийся приём для удержания документа внутри вашей границы, как описано в эталонной модели EU Digital Signature Service (DSS).
Провайдер подписывает дайджест версией ключа, которую он разрешает, и возвращает «сырую» подпись.
Сессия собирает CMS SignedData и встраивает его в PDF.

Провайдеры реализованы поверх чистых вызовов Hypertext Transfer Protocol (HTTP) по PSR-18 — без зависимости от software development kit (SDK) облачного вендора. Аутентификация делегируется вашему приложению: вы передаёте bearer-токен (AWS, GCP) либо токен или учётные данные сервис-принципала (Azure). Каждый провайдер нормализует свой вывод для CMS: AWS и GCP возвращают подписи Rivest–Shamir–Adleman (RSA) в форме DER, готовой для CMS; подпись Elliptic Curve Digital Signature Algorithm (ECDSA), которую провайдер возвращает как «сырую» пару целых чисел (Azure), преобразуется в форму с кодировкой DER, тогда как GCP возвращает ECDSA уже в кодировке DER. Кривая ECDSA и дайджест сопоставлены по соглашению — P-256 с SHA-256, P-384 с SHA-384, P-521 с SHA-512 — согласно рекомендованному сопоставлению в RFC 5480.

Реестр PSR-11 разрешает провайдеров по идентификатору и поддерживает ленивые фабрики. Enterprise-клиенты с собственным хостингом регистрируют проприетарный драйвер HSM или KMS, реализуя контракт провайдера и привязывая его в реестре, — без форка NextPDF Pro.

Семантика версий ключа для каждого провайдера

Провайдеры предоставляют разные примитивы «активной версии», поэтому поведение версии ключа по умолчанию различается:

AWS KMS — версия ключа null использует псевдоним ключа, который AWS разрешает в текущую версию ключа на стороне провайдера.
Azure Key Vault — версия ключа null использует URL ключа без версии, который Azure разрешает в последнюю включённую версию. Явное переопределение должно быть 32-символьным шестнадцатеричным идентификатором; любое другое значение отклоняется, чтобы предотвратить инъекцию сегмента URL.
GCP Cloud KMS — конечная точка асимметричного подписания работает только с конкретной версией криптоключа; «активной версии» на стороне сервера нет. Вы должны зафиксировать версию в конфигурации или передать её явно. Если ни то ни другое не задано, подписант выдаёт ошибку управления ключами, а не угадывает.

Задокументируйте, какой режим использует ваше развёртывание, чтобы поведение было детерминированным.

Предварительные требования

Установите NextPDF Core и пакет Pro и имейте активную лицензию Pro.
Подготовьте ключ подписания у выбранного провайдера и запишите его идентификаторы (псевдоним ключа или Amazon Resource Name для AWS; имя хранилища и ключа для Azure; проект, расположение, кольцо ключей, криптоключ и версию для GCP).
Предоставьте HTTP-клиент PSR-18 и фабрики запросов и потоков PSR-17.
Получите учётные данные провайдера в своём приложении: bearer-токен для AWS или GCP либо предварительно полученный токен или учётные данные сервис-принципала для Azure. Получение токена — зона ответственности вашего приложения; подавайте секреты из своего менеджера секретов, никогда из исходного кода.

Конфигурация

У каждого провайдера есть неизменяемый объект конфигурации, построенный из ваших идентификаторов и учётных данных. Общие аспекты конфигурации:

Идентификатор провайдера — aws-kms, azure-keyvault или gcp-kms, используется как ключ поиска в реестре.
Алгоритм — выбирается для каждого вызова из имени алгоритма, которое передаёт ваша сессия подписания; провайдер отклоняет алгоритм, который он не поддерживает.
Версия ключа — зафиксирована в конфигурации или передана для каждого вызова, с описанной выше семантикой для каждого провайдера.
Учётные данные — bearer-токен или учётные данные сервис-принципала, которые ваше приложение подаёт из своего менеджера секретов.

Пошагово

Постройте конфигурацию провайдера из ваших идентификаторов и учётных данных, считанных из менеджера секретов.
Создайте подписант провайдера с конфигурацией, сертификатом подписанта в форме DER, цепочкой, клиентом PSR-18 и фабриками PSR-17.
При необходимости зарегистрируйте провайдер в реестре PSR-11 под его идентификатором, чтобы оркестратор разрешал его по имени.
Запустите сессию подписания Pro: она вычисляет дайджест, формирует подписанные атрибуты и вызывает провайдер только с дайджестом.
Перехватите наиболее конкретный сбой — управления ключами, неподдерживаемого алгоритма или неудавшейся подписи, — запишите в журнал структурное сообщение без секретов и повторно выбросите исключение.

<?php

declare(strict_types=1);

require_once __DIR__ . '/../../vendor/autoload.php';

use NextPDF\Pro\Security\Signing\Kms\KeyManagementProviderRegistry;
use NextPDF\Pro\Security\Signing\Kms\KmsSignerInterface;

/**
 * Register cloud-KMS providers behind one registry resolved by identifier.
 *
 * Each provider is supplied as a lazy factory so a provider is only
 * constructed when first resolved. The caller depends on the registry and
 * the provider contract, not on a concrete provider class.
 *
 * @param array<non-empty-string, callable(): KmsSignerInterface> $factories
 *        Provider factories keyed by provider identifier.
 *
 * @return KeyManagementProviderRegistry The populated registry.
 */
function buildKmsRegistry(array $factories): KeyManagementProviderRegistry
{
    $registry = new KeyManagementProviderRegistry();

    foreach ($factories as $providerId => $factory) {
        $registry->registerFactory($providerId, $factory);
    }

    return $registry;
}

<?php

declare(strict_types=1);

require_once __DIR__ . '/../../vendor/autoload.php';

use NextPDF\Pro\Security\Signing\Kms\KmsSignerInterface;
use NextPDF\Pro\Security\Exception\KeyManagementException;
use NextPDF\Pro\Security\Exception\SignatureFailedException;
use NextPDF\Pro\Security\Exception\UnsupportedAlgorithmException;
use Psr\Log\LoggerInterface;

final readonly class KmsSigningService
{
    public function __construct(
        private KmsSignerInterface $provider,
        private LoggerInterface $logger,
    ) {}

    /**
     * Sign a signed-attributes digest with a pinned key version.
     *
     * Only the digest is sent to the provider; the document stays on the
     * host. Each failure mode is caught as its most specific type so the
     * caller can distinguish a key-version problem from a transport failure.
     *
     * @param string      $digest     The signed-attributes digest to sign.
     * @param string      $algorithm  The OpenSSL-style algorithm name.
     * @param string|null $keyVersion The pinned key version, or null for the
     *                                 provider default (per-provider semantics).
     *
     * @throws KeyManagementException        When the key version is unknown or required and absent.
     * @throws UnsupportedAlgorithmException When the provider does not support the algorithm.
     * @throws SignatureFailedException      When the provider sign operation fails.
     *
     * @return string The raw signature bytes (DER for RSA and ECDSA per CMS rules).
     */
    public function sign(string $digest, string $algorithm, ?string $keyVersion): string
    {
        try {
            return $this->provider->signWithVersion($digest, $algorithm, $keyVersion);
        } catch (KeyManagementException | UnsupportedAlgorithmException | SignatureFailedException $e) {
            $this->logger->error('KMS signing failed', [
                'provider' => $this->provider->providerId(),
                'reason'   => $e->getMessage(),
            ]);

            throw $e;
        }
    }
}

Проверка

Убедитесь, что провайдер самоописывает алгоритм, который вы собираетесь использовать, до подписания, чтобы неподдерживаемый алгоритм был пойман на этапе выбора, а не при вызове провайдера.
Убедитесь, что передаётся только дайджест: байты документа не должны появляться в теле запроса к провайдеру. Запрос несёт дайджест в кодировке base64, а не файл.
Для ECDSA убедитесь, что встроенная подпись имеет кодировку DER — подписант преобразует подпись из «сырой» пары целых чисел за вас.
Откройте подписанный PDF в валидаторе, настроенном на ваши якоря доверия, и убедитесь, что подпись сообщается как криптографически целостная. Сформированная подпись — это не проверенная подпись; решение о доверии принадлежит проверяющему.
Убедитесь, что ни токен, ни учётные данные, ни ключевой материал не появляются в журналах вашего приложения.

Безопасность и соответствие требованиям

Ключ остаётся у провайдера. Стратегия облачного KMS — точка интеграции, а не хранилище ключей. NextPDF Pro не хранит закрытый ключ для стратегии KMS.
Границу пересекает только дайджест. Сессия отправляет провайдеру дайджест подписанных атрибутов, а не документ — приём с входным дайджестом сообщения, описанный в эталонной модели EU DSS.
Диапазон байтов вычисляет движок. Он никогда не принимается от вызывающей стороны.
Отказ в закрытое состояние. Сбой провайдера, сети, версии ключа или неподдерживаемого алгоритма выбрасывает типизированное исключение. Сессия не создаёт молча неподписанный документ и никогда не подменяет алгоритм более слабым.
Учётные данные — это секреты. Токены и учётные данные сервис-принципала поступают из вашего менеджера секретов и исключаются из журналов.

Эта страница касается криптографического подписания. Каждый нормативный источник перефразирован; нормативный текст не воспроизводится. ### Граница хранения ключа

Защита ключа зависит от обращения с ключом, настроенного KMS и развёртывания. NextPDF Pro предоставляет интеграцию с KMS, а не хранилище ключей. NextPDF Pro совместим с FIPS только при настройке против KMS или HSM, валидированного по FIPS; сам он не является криптографическим модулем, валидированным по FIPS, и не заявляет о сертификации FIPS.

Обработка сбоев

Неизвестная или отключённая версия ключа. Провайдер отображает ответ «не найдено» или «версия отключена» в исключение управления ключами, которое называет провайдер и ключ.
GCP без зафиксированной версии. Подписант GCP выдаёт ошибку управления ключами, когда ни конфигурация, ни вызов не предоставляют версию, поскольку конечная точка асимметричного подписания работает только с конкретной версией.
Неподдерживаемый алгоритм. Запрос алгоритма, который провайдер не поддерживает, выбрасывает исключение неподдерживаемого алгоритма до какого-либо сетевого вызова.
Сбой транспорта. Ошибка клиента PSR-18 отображается в исключение неудавшейся подписи; сессия не создаёт частичный результат.
Отсутствующие учётные данные. Подписант без токена и без учётных данных сервис-принципала выдаёт типизированную ошибку, а не вызывает провайдер без аутентификации.

См. также

Безопасность — NextPDF Pro — маскирование, обнаружение PII и полная поверхность подписания Pro.
Подписание HSM — NextPDF Enterprise — аппаратное хранение ключей PKCS#11.
Подпись — NextPDF Enterprise — производитель долгосрочных подписей PAdES B-LT и B-LTA.
Безопасность / Подписание (Core) — подписант CMS из Core и контракт стратегии подписания.
KMS · CMS · ECDSA · HSM — термины глоссария.