💡 Полный рабочий пример доступен на GitHub: sign-pdf-with-vault-managed-key-java

Старый способ был болезненным

Runbook для Java‑сервиса подписи обычно содержит шаг, который никто не любит писать: скопировать signing.pfx на новый хост, затем поместить пароль в переменные окружения. С этого момента приватный ключ существует как минимум в трёх дополнительных местах, чем предполагалось. Он находится в слое образа, в резервной копии хоста и в памяти JVM, которая его загружает, где дамп кучи с радостью покажет его тому, у кого есть дамп.

External signing — это возможность GroupDocs.Signature для Java, которая передаёт дайджест документа в ваш callback вместо подписи приватным ключом, загружаемым приложением. Это то, что позволяет избавиться от этого шага в runbook. Ключ подписи перемещается в HashiCorp Vault, сервис хранит токен вместо ключа, и единственное значение, передаваемое по сети во время подписи, — это 32‑байтовый хеш.

Команды используют это, когда в ревью задают очевидный вопрос — «кто ещё может подписывать от вашего имени» — и честный ответ: «любой, кто когда‑либо имел доступ к этому файлу». Ограничение доступа к файлу с помощью прав и зашифрованного тома сужает окно; но не удаляет копию.

Есть лучший способ

Vault Transit engine предоставляет криптографию как сервис. Вы отправляете ему значение, он подписывает его своим ключом и возвращает результат. Ключ, созданный внутри Transit, может быть помечен как non‑exportable, поэтому нечего копировать на хост, а Vault не хранит то, что вы ему отправляете.

Это помогает только если библиотека подписи может делегировать, и здесь на сцену выходит GroupDocs.Signature. DigitalSignOptions.setCustomSignHash принимает callback. Библиотека делает всё до криптографии: открывает PDF, определяет диапазон байтов, покрываемый подписью, хеширует их, вызывает ваш callback с дайджестом, затем встраивает полученные байты вместе с сертификатом.

Вам нужны JDK 8 или новее, Maven, Docker для локального Vault и BouncyCastle для сертификата. Пример работает с GroupDocs.Signature for Java 26.10; без лицензии режим оценки принимает документы до 2‑х страниц.

Новый способ: обратный вызов вместо файла ключа

Шаг 1 — Чтение ключа из Vault

Сервис запрашивает у Vault ключ, который ему разрешено использовать, и получает номер версии с публичным ключом. Приватная часть никогда не присутствует в ответе.

VaultKey key = vault.readKey(KEY_NAME);
if (key == null) {
    vault.enableTransit();
    vault.createKey(KEY_NAME, "rsa-2048");
    key = vault.readKey(KEY_NAME);
}

404 от Vault означает, что либо ключ, либо монтирование Transit отсутствует, поэтому пример рассматривает это как первичную настройку, а не как ошибку. В продакшене администратор включает Transit и создаёт ключ заранее, а токен приложения не имеет прав ни на то, ни на другое.

Прочитайте версию один раз и храните её. Сертификат содержит ровно один публичный ключ, поэтому сертификат и каждая подпись должны исходить из одной и той же версии.

Шаг 2 — Создание сертификата вокруг публичной части

PDF‑подпись содержит сертификат X.509, чтобы проверяющий мог найти публичный ключ. В JDK нет способа построить сертификат, подпись которого берётся откуда‑то ещё, но BouncyCastle умеет: X509v3CertificateBuilder делегирует ContentSigner, а ContentSigner, поддерживаемый Vault, занимает около пятнадцати строк.

@Override
public byte[] getSignature() {
    try {
        byte[] digest =
            MessageDigest.getInstance("SHA-256").digest(data.toByteArray());
        return vault.signHash(keyName, keyVersion, digest, "sha2-256");
    } catch (IOException e) {
        throw new UncheckedIOException(e);
    }
}

BouncyCastle записывает байты, которые нужно подписать, в поток подписанта, а затем запрашивает подпись. Байты хешируются локально, и только дайджест отправляется в Vault. Интерфейс не объявляет проверяемых исключений, поэтому сбой Vault должен быть обёрнут и распакован вызывающим кодом; если этого не сделать, 403 от Vault проявится как загадочная ошибка времени выполнения.

Шаг 3 — Подписать, затем проверить в том же запуске

DigitalSignature digitalSignature = new DigitalSignature();
digitalSignature.setX509Certificate(certificate);

DigitalSignOptions options = new DigitalSignOptions();
options.setSignature(digitalSignature);
options.setCustomSignHash(signer::customSignHash);
options.setHashAlgorithm(HashAlgorithm.Sha256);

ByteArrayOutputStream signedPdf = new ByteArrayOutputStream();
signature.sign(signedPdf, options);
Files.write(outputPdf, trimTrailingZeros(signedPdf.toByteArray()));

Внутри callback дайджест отправляется в transit/sign с двумя полями, определяющими валидность результата: prehashed = true, потому что вход уже является хешем, и signature_algorithm = pkcs1v15, поскольку Vault по умолчанию использует PSS для RSA‑ключей, а подпись PDF — sha256WithRSAEncryption.

Затем проверяем до того, как файл куда‑либо отправится. Подпись и проверка в одном запуске превращают единственный «тихий» режим отказа в мгновенный.

Сравнение: до и после

PFX на хосте Vault Transit обратный вызов
Копии приватного ключа одна на каждый хост, образ и резервную копию одна, внутри Vault
Что хранит сервис ключ и его пароль токен с правами на две операции
Шаг развертывания для нового хоста скопировать PFX, установить пароль ничего
Запись каждой подписи логи приложения, если они записаны одна запись аудита Vault
После подозрения на утечку отозвать, переиздать, переразвернуть везде ротация в Vault, переиздание один раз
Кто может подписывать от вашего имени любой, у кого есть файл и пароль любой, у кого есть действительный токен Vault

Последняя строка стоит сказать откровенно: это перемещает секрет, а не уничтожает его. Разница в том, что токен короткоживущий, отзываемый в одном месте, ограничен чтением одного ключа и вызовом sign, и каждый его использованный момент фиксируется в журнале.

Пример из реального мира: сервис выписок

Сервис генерирует ежемесячные выписки и подписывает каждую перед размещением в клиентском портале. При старой схеме образ контейнера нес сертификат, и три человека знали пароль, потому что кто‑то должен был его ротировать. С callback образ не содержит никаких секретов: pod получает AppRole‑токен при старте, политика в vault/sample-signer.hcl позволяет читать ключ и подписывать им, а любые другие попытки токена возвращают 403 permission denied.

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

Ротация — это место, где дизайн оправдывает себя, но также где может «кусать». После transit/keys/:name/rotate Vault подписывает новейшей версией, если не указано иначе, поэтому сертификат, построенный для версии 1, в сочетании с подписью версии 2 даёт PDF, который не сообщает об ошибке, но и не проходит проверку. Поскольку подписант создаётся с одной версией, такой случай здесь невозможен: сервис выписок продолжает подписывать версией, к которой относится его сертификат, пока кто‑то не выпустит новый сертификат для новой версии. Установка min_encryption_version на ключ после этого делает старую версию непригодной, и Vault сообщает об отказе подписи, а не о плохой подписи.

Какие особенности следует ожидать в версии 26.10?

Четыре, все обнаружены во время сборки. Имя метода ICustomSignHash в jar‑файле обфусцировано, поэтому передайте ссылку на метод, а не реализуйте интерфейс. Подписанный вывод содержит завершающие нулевые байты за пределами подписи, их нужно обрезать. DigitalVerifyOptions требует файл сертификата, а не поток. И видимая область подписи требует установленный шрифт Arial.

Что ещё можно сделать с GroupDocs.Signature?

Callback не знает, что находится за ним, поэтому те же три шага работают с аппаратным модулем, смарт‑картой или облачным KMS. Я портировал это из .NET и Python‑версий того же примера, и тело запроса к Vault пришло без изменений; построение сертификата и эти четыре особенности — единственные действительно Java‑специфичные части. Помимо цифровых подписей библиотека также добавляет и ищет подписи текста, изображения, штрих‑кода, QR‑кода и метаданных в PDF, Word, Excel, PowerPoint и графических форматах.

Заключение

Подписание PDF в Java без хранения приватного ключа требует callback, сертификата, построенного вокруг публичного ключа, и токена с двумя правами. Пример работает с Vault в режиме разработки двумя командами, а тот же код переключается на продакшн‑Vault изменением VAULT_ADDR и VAULT_TOKEN.

Дополнительные ресурсы