💡 Повний робочий приклад доступний на GitHub:
sign-pdf-with-vault-managed-key-java
Старий спосіб був болючим
Runbook для Java‑сервісу підпису, як правило, містить крок, який ніхто не любить записувати: скопіювати signing.pfx на новий хост, а потім помістити пароль у середовище. З того моменту приватний ключ існує принаймні в трьох додаткових місцях, ніж планувалося. Він знаходиться у шарі образу, у резервній копії хоста та у пам’яті JVM, яка його завантажує, і дамп heap‑у з радістю покаже його тому, хто має дамп.
External signing — це можливість GroupDocs.Signature для Java, яка передає дайджест документа у зворотний виклик, який ви надаєте, замість підпису приватним ключем, що завантажується додатком. Це частина, яка дозволяє видалити цей крок з runbook‑а. Ключ підпису переміщується в HashiCorp Vault, сервіс зберігає токен замість ключа, і єдине значення, що передається по мережі під час підпису, — це 32‑байтовий хеш.
Команди звертаються до цього, коли під час рев’ю задають очевидне питання — «хто ще може підписати від вашого імені» — і чесна відповідь звучить: «будь‑хто, хто коли‑небудь мав доступ до цього файлу». Обмеження доступу до файлу за допомогою прав і зашифрованого тому звужує вікно; воно не усуває копію.
Є кращий спосіб
Transit‑движок Vault виконує криптографію як сервіс. Ви надсилаєте йому значення, він підписує його своїм ключем і повертає результат. Ключ, створений у Transit, може бути позначений як неекспортований, тому немає нічого, що треба копіювати на хост, а Vault не зберігає те, що ви йому надсилаєте.
Це допомагає лише тоді, коли бібліотека підпису може делегувати, і саме тут вступає в гру GroupDocs.Signature. DigitalSignOptions.setCustomSignHash приймає зворотний виклик. Бібліотека робить усе до криптографії: відкриває PDF, визначає діапазон байтів, який охоплює підпис, хешує його, викликає ваш зворотний виклик з дайджестом, а потім вбудовує отримані байти разом із сертифікатом.
Потрібні 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()));
Всередині зворотного виклику дайджест надсилається до transit/sign з двома полями, що визначають, чи результат дійсний: prehashed = true, бо вхід вже є хешем, і signature_algorithm = pkcs1v15, бо Vault за замовчуванням використовує PSS для RSA‑ключів, тоді як PDF‑підпис — це sha256WithRSAEncryption.
Потім перевірте перед тим, як файл кудись передати. Підпис і перевірка в одному запуску перетворює єдиний «тихий» режим збою на негайний.
Порівняння: до і після
| PFX на хості | Vault Transit зворотний виклик | |
|---|---|---|
| Копії приватного ключа | одна на хост, образ і резервну копію | одна, всередині Vault |
| Що зберігає сервіс | ключ і його пароль | токен, що охоплює дві операції |
| Крок розгортання для нового хоста | скопіювати PFX, встановити пароль | нічого |
| Запис кожного підпису | журнали застосунку, якщо вони ведуться | один запис аудиту Vault |
| Після підозри на витік | відкликати, переоформити, розгорнути скрізь | повернути в Vault, переоформити один раз |
| Хто може підписати від вашого імені | будь‑хто, хто має файл і пароль | будь‑хто, у кого є дійсний токен Vault |
Останній рядок варто сформулювати чітко: це переміщує секрет, а не знищує його. Різниця в тому, що токен короткоживущий, відкликуваний в одному місці, обмежений лише читанням одного ключа і викликом підпису, і кожного разу, коли його використовують, він журналюється.
Приклад з реального світу: сервіс виписок
Сервіс генерує щомісячні виписки і підписує кожну перед тим, як розмістити її у порталі клієнта. За старого підходу образ контейнера містив сертифікат, і три людини мали пароль, бо хтось мусив його обертати. За допомогою зворотного виклику образ не містить жодного секрету: 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?
Зворотний виклик не знає, що стоїть за ним, тому ті ж три кроки працюють з апаратним модулем, смарт‑карткою або хмарним KMS. Я портировав це з .NET‑ і Python‑версій того ж прикладу, і тіло запиту до Vault залишилося незмінним; конструювання сертифікату та ці чотири особливості — єдині справді Java‑специфічні частини. Окрім цифрових підписів бібліотека також додає та шукає підписи тексту, зображень, штрих‑коду, QR‑коду та метаданих у PDF, Word, Excel, PowerPoint та графічних форматах.
Висновок
Підпис PDF у Java без зберігання приватного ключа вимагає зворотного виклику, сертифікату, створеного навколо публічного ключа, і токену з двома правами. Приклад працює проти Vault у режимі розробки за допомогою двох команд, а той самий код можна спрямувати на продакшн‑Vault, змінивши VAULT_ADDR і VAULT_TOKEN.