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

Додаткові ресурси