💡 Полный рабочий пример доступен на 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.