💡 Pełny działający przykład dostępny na GitHub: sign-pdf-with-vault-managed-key-java

Stara metoda była bolesna

Runbook dla usługi podpisywania w Javie zazwyczaj zawiera krok, którego nikt nie lubi zapisywać: skopiowanie signing.pfx na nowy host, a następnie umieszczenie hasła w zmiennych środowiskowych. Od tej chwili klucz prywatny istnieje w co najmniej trzech dodatkowych miejscach, niż ktokolwiek zamierzał. Jest w warstwie obrazu, w kopii zapasowej hosta i w pamięci JVM, która go ładuje, gdzie zrzut sterty chętnie pokaże go każdemu, kto posiada zrzut.

External signing to funkcja GroupDocs.Signature dla Javy, która przekazuje skrót dokumentu do wywołania zwrotnego podanego przez Ciebie, zamiast podpisywać go kluczem prywatnym ładowanym przez aplikację. To element, który pozwala usunąć ten krok z runbooka. Klucz podpisujący przenosi się do HashiCorp Vault, usługa przechowuje token zamiast klucza, a jedyną wartością przesyłaną podczas podpisywania jest 32‑bajtowy hash.

Zespoły sięgają po to rozwiązanie, gdy w przeglądzie pada oczywiste pytanie – kto jeszcze może podpisywać w Twoim imieniu – a szczera odpowiedź brzmi „każdy, kto kiedykolwiek miał dostęp do tego pliku”. Zablokowanie pliku uprawnieniami i zaszyfrowanym wolumenem zawęża okno możliwości; nie usuwa jednak kopii.

Jest lepszy sposób

Silnik Transit w Vault realizuje kryptografię jako usługę. Wysyłasz mu wartość, on podpisuje ją kluczem, który posiada, i zwraca wynik. Klucz utworzony w Transit może być oznaczony jako nieeksportowalny, więc nie ma nic do kopiowania na hosta, a Vault nie przechowuje tego, co mu wysyłasz.

To pomaga tylko wtedy, gdy biblioteka podpisująca potrafi delegować, a tutaj wkracza GroupDocs.Signature. DigitalSignOptions.setCustomSignHash przyjmuje wywołanie zwrotne. Biblioteka robi wszystko aż do kryptografii: otwiera PDF, wylicza zakres bajtów objętych podpisem, hashuje je, wywołuje Twoje wywołanie zwrotne z digestem, a następnie osadza zwrócone bajty razem z certyfikatem.

Potrzebujesz JDK 8 lub nowszego, Maven, Docker do lokalnego Vault oraz BouncyCastle do obsługi certyfikatu. Przykład działa z GroupDocs.Signature dla Javy 26.10; bez licencji tryb ewaluacyjny akceptuje dokumenty do 2 stron.

Nowy sposób: wywołanie zwrotne zamiast pliku klucza

Krok 1 – Odczytaj klucz z Vault

Usługa pyta Vault o klucz, którego może używać, i otrzymuje numer wersji wraz z kluczem publicznym. Część prywatna nigdy nie znajduje się w odpowiedzi.

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

Kod 404 od Vault oznacza, że brak klucza lub punktu montowania Transit, więc przykład traktuje to jako konfigurację przy pierwszym uruchomieniu, a nie jako błąd. W środowisku produkcyjnym administrator włącza Transit i tworzy klucz z wyprzedzeniem, a token aplikacji nie ma uprawnień do żadnej z tych operacji.

Odczytaj wersję raz i zachowaj ją. Certyfikat zawiera dokładnie jeden klucz publiczny, więc certyfikat i każdy podpis muszą pochodzić z tej samej wersji.

Krok 2 – Zbuduj certyfikat wokół części publicznej

Podpis PDF zawiera certyfikat X.509, aby weryfikator mógł odnaleźć klucz publiczny. JDK nie potrafi zbudować certyfikatu, którego podpis pochodzi z innego źródła, ale BouncyCastle tak: X509v3CertificateBuilder deleguje do ContentSigner, a ContentSigner oparty na Vault składa się z około piętnastu linii.

@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 zapisuje bajty do podpisania do strumienia sygnującego, a następnie żąda podpisu. Bajty są haszowane lokalnie, a do Vault trafia jedynie digest. Interfejs nie deklaruje żadnych sprawdzonych wyjątków, więc awaria Vault musi zostać opakowana i odpakowana przez wywołującego; pominięcie tego powoduje, że 403 od Vault pojawia się jako zagadkowy błąd w czasie wykonywania.

Krok 3 – Podpisz, a następnie zweryfikuj w tym samym uruchomieniu

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()));

Wewnątrz wywołania zwrotnego digest jest wysyłany do transit/sign z dwoma polami decydującymi o poprawności wyniku: prehashed = true, ponieważ wejście jest już hashem, oraz signature_algorithm = pkcs1v15, ponieważ Vault domyślnie używa PSS dla kluczy RSA, a podpis PDF to sha256WithRSAEncryption.

Następnie weryfikuj, zanim plik trafi gdziekolwiek. Podpisywanie i weryfikacja w jednym przebiegu to sposób na przekształcenie jedynego trybu cichej awarii w natychmiastową.

Porównanie: przed i po

PFX na hoście Wywołanie zwrotne Vault Transit
Kopie klucza prywatnego jedna na każdy host, obraz i kopię zapasową jedna, wewnątrz Vault
Co przechowuje usługa klucz i jego hasło token z zakresem dwóch operacji
Krok wdrożenia dla nowego hosta skopiuj PFX, ustaw hasło nic
Rekord każdego podpisu logi aplikacji, jeśli są zapisywane jeden wpis audytu Vault
Po podejrzeniu wycieku odwołaj, wydaj ponownie, wdroż wszędzie rotuj w Vault, wydaj ponownie raz
Kto może podpisywać w Twoim imieniu każdy, kto ma plik i hasło każdy, kto ma ważny token Vault

Ostatni wiersz warto sformułować wprost: to przenosi sekret, a nie go eliminuje. Różnica polega na tym, że token jest krótkotrwały, odwoływalny w jednym miejscu, ograniczony do odczytu jednego klucza i wywołania podpisu oraz logowany przy każdym użyciu.

Przykład z życia: usługa wyciągów

Usługa generuje miesięczne wyciągi i podpisuje każdy z nich, zanim umieści je w portalu klienta. W starej konfiguracji obraz kontenera zawierał certyfikat, a trzech ludzi znało hasło, ponieważ ktoś musiał je rotować. Przy użyciu wywołania zwrotnego obraz nie zawiera żadnego sekretu: pod otrzymuje token AppRole przy starcie, polityka w vault/sample-signer.hcl zezwala na odczyt klucza i podpisywanie, a każda inna próba tokena zwraca 403 permission denied.

Gdy audytor pyta, ile dokumentów zostało podpisanych w marcu i jaką wersją klucza, odpowiedź pochodzi z urządzenia audytu Vault, a nie z przeszukiwania logów aplikacji.

Rotacja to miejsce, w którym to rozwiązanie naprawdę się opłaca, ale także może sprawić problemy. Po wywołaniu transit/keys/:name/rotate Vault podpisuje najnowszą wersją, chyba że wskażesz inaczej, więc certyfikat zbudowany dla wersji 1 połączony z podpisem z wersji 2 daje PDF, który nie zgłasza błędu, ale nie przechodzi weryfikacji. Ponieważ sygnujący jest skonstruowany z jedną wersją, nie może tak się stać przypadkowo: usługa wyciągów podpisuje dalej wersją, do której należy jej certyfikat, dopóki ktoś nie wyda nowego certyfikatu dla nowej wersji. Ustawienie min_encryption_version na kluczu po rotacji uniemożliwia użycie starej wersji, co Vault zgłasza jako odmowę podpisu, a nie jako nieprawidłowy podpis.

Jakie dziwactwa powinienem się spodziewać w wersji 26.10?

Cztery, wszystkie odkryte podczas budowania tego przykładu. Nazwa metody ICustomSignHash jest zamaskowana w pliku JAR, więc przekaż referencję do metody zamiast implementować interfejs. Podpisany wynik zawiera końcowe bajty zero poza podpisem, więc trzeba je przyciąć. DigitalVerifyOptions wymaga pliku certyfikatu, a nie strumienia. I wreszcie widoczny prostokąt podpisu wymaga zainstalowanego fontu Arial.

Co jeszcze możesz zrobić z GroupDocs.Signature?

Wywołanie zwrotne nie wie, co znajduje się „za nim”, więc te same trzy kroki działają z modułem sprzętowym, kartą inteligentną lub chmurowym KMS. Przeniosłem to z wersji .NET i Pythona tego samego przykładu, a ciało żądania do Vault przeszło niezmienione; konstrukcja certyfikatu i te cztery dziwactwa to jedyne elementy naprawdę specyficzne dla Javy. Poza podpisami cyfrowymi biblioteka umożliwia także dodawanie i wyszukiwanie podpisów tekstowych, graficznych, kodów kreskowych, QR oraz metadanych w formatach PDF, Word, Excel, PowerPoint i obrazach.

Wnioski

Podpisanie PDF w Javie bez przechowywania klucza prywatnego wymaga wywołania zwrotnego, certyfikatu zbudowanego wokół klucza publicznego oraz tokenu z dwoma uprawnieniami. Przykład działa przeciwko Vault w trybie deweloperskim przy użyciu dwóch poleceń, a ten sam kod wskazuje na produkcyjny Vault po zmianie VAULT_ADDR i VAULT_TOKEN.

Dodatkowe zasoby