💡 Tam çalışan örnek GitHub’da mevcuttur: sign-pdf-with-vault-managed-key-java

Eski Yöntem Zorlayıcıydı

Java imzalama servisi için çalışma kitabı, kimsenin yazmak istemediği bir adım içerir: signing.pfx dosyasını yeni ana bilgisayara kopyalamak, ardından şifreyi ortam değişkenine koymak. Bu andan itibaren özel anahtar, kimsenin amaçladığından en az üç yerde daha bulunur. Görüntü katmanında, ana bilgisayarın yedeğinde ve onu yükleyen JVM’in belleğinde bulunur; bir yığın dökümü, dökümü elinde bulunduran herkese bunu mutlu bir şekilde gösterir.

External signing, GroupDocs.Signature’ın Java için bir yeteneğidir ve uygulamanın yüklediği bir özel anahtar ile imzalamak yerine belge özetini sağladığınız bir geri çağrıya verir. Bu, çalışma kitabı adımını silmenizi sağlayan parçadır. İmzalama anahtarı HashiCorp Vault’a taşınır, hizmet bir anahtar yerine bir token tutar ve imzalama sırasında kabloyu geçen tek değer 32 baytlık bir hash olur.

Ekipler, bir inceleme açıkça “Sizin adınıza kim daha imzalayabilir?” sorusunu sorduğunda buna yönelir ve dürüst cevap “o dosyaya bir zaman erişmiş olan herkes”tir. Dosyayı izinlerle ve şifreli bir birimle kilitlemek pencereyi daraltır; kopyayı ortadan kaldırmaz.

Daha İyi Bir Yol Var

Vault’un Transit motoru, hizmet olarak kriptografi yapar. Ona bir değer gönderirsiniz, tuttuğu bir anahtar ile imzalar ve sonucu döndürür. Transit içinde oluşturulan bir anahtar dışa aktarılabilir olarak işaretlenemez, böylece başta bir ana bilgisayara kopyalanacak bir şey olmaz ve Vault gönderdiğiniz şeyi saklamaz.

Bu sadece imzalama kütüphanesi devretme yapabiliyorsa işe yarar; işte bu noktada GroupDocs.Signature devreye girer. DigitalSignOptions.setCustomSignHash bir geri çağrı alır. Kütüphane kriptografiye kadar her şeyi yapar: PDF’i açar, imzanın kapsadığı bayt aralığını belirler, hash’ini alır, özetle geri çağrınızı çağırır, ardından geri gelen baytları sertifika ile birlikte gömer.

JDK 8 veya daha yenisi, Maven, yerel bir Vault için Docker ve sertifika için BouncyCastle gerekir. Örnek, GroupDocs.Signature for Java 26.10 ile çalışır; lisans olmadan değerlendirme modu en fazla 2 sayfalık belgeleri kabul eder.

Yeni Yöntem: Anahtar Dosyası Yerine Bir Geri Çağrı

Adım 1 - Anahtarı Vault’tan Okuma

Servis, kullanmasına izin verilen anahtarı Vault’tan ister ve bir genel anahtarlı sürüm numarası alır. Özel yarı asla yanıt içinde bulunmaz.

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

Vault’tan bir 404, ya anahtarın ya da Transit bağlamının eksik olduğu anlamına gelir; bu yüzden örnek bunu bir hata yerine ilk kurulum olarak ele alır. Üretimde bir yönetici Transit’i etkinleştirir ve anahtarı önceden oluşturur, uygulamanın token’ı ise ikisinde de işlem yapmaya yetkili değildir.

Sürümü bir kez okuyun ve saklayın. Bir sertifika tam olarak bir genel anahtar tutar, bu yüzden sertifika ve her imza aynı sürümden gelmelidir.

Adım 2 - Genel Yarı Çevresinde Bir Sertifika Oluşturma

PDF imzası, doğrulayıcının genel anahtarı bulabilmesi için bir X.509 sertifikası taşır. JDK, imzası başka bir yerden gelen bir sertifika oluşturamaz, ancak BouncyCastle bunu yapar: X509v3CertificateBuilder bir ContentSigner‘a devredilir ve Vault tarafından desteklenen bir ContentSigner yaklaşık on beş satırdır.

@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, imzalanacak baytları imzalayanın akışına yazar ve ardından imzayı ister. Baytlar yerel olarak hash’lenir ve sadece özet Vault’a gider. Arayüz kontrol edilen istisnalar tanımlamaz, bu yüzden bir Vault hatası sarmalanmış olarak dışarı çıkmalı ve çağıran tarafından çözümlenmelidir; bunu atlayıp bir 403 hatası alındığında, Vault’tan gelen bu durum şaşırtıcı bir çalışma zamanı hatası olarak ortaya çıkar.

Adım 3 - İmzala, ardından aynı çalışmada doğrula

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

Geri çağrı içinde özet, transit/sign‘e iki alanla gönderilir; bu alanlar sonucun geçerli olup olmadığını belirler: prehashed = true, çünkü girdi zaten bir hash’tir, ve signature_algorithm = pkcs1v15, çünkü Vault RSA anahtarları için varsayılanı PSS iken PDF imzası sha256WithRSAEncryption’dır.

Dosya bir yere gitmeden önce doğrulama yapın. Tek bir çalışmada imzalama ve doğrulama, tek sessiz hata modunu anında bir hataya dönüştüren şeydir.

Yan Yana: Önce ve Sonra

Ana bilgisayarda PFX Vault Transit geri çağrısı
Özel anahtarın kopyaları her ana bilgisayar, imaj ve yedek için bir bir, Vault içinde
Servisin tuttuğu anahtar ve şifresi iki işlemi kapsayan bir token
Yeni bir ana bilgisayar için dağıtım adımı PFX’i kopyala, şifreyi ayarla hiçbir şey
Her imzanın kaydı uygulama günlükleri, eğer yazıldıysa bir Vault denetim girişi
Şüpheli bir sızıntı sonrası iptal et, yeniden düzenle, her yerde yeniden dağıt Vault içinde döndür, bir kez yeniden düzenle
Sizin adınıza kim imzalayabilir dosyaya ve şifreye sahip olan herkes geçerli bir Vault tokenına sahip olan herkes

Son satır açıkça söylenmeye değerdir: bu, sırrı ortadan kaldırmak yerine taşır. Fark, token’ın kısa ömürlü, tek bir yerde iptal edilebilir, bir anahtarı okuma ve imzalama ile sınırlı ve her kullanıldığında kaydedilmiş olmasıdır.

Gerçek Dünya Örneği: Bir Bildirim Servisi

Bir servis aylık bildirimler üretir ve her birini müşteri portalına bırakmadan önce imzalar. Eski düzenlemede konteyner görüntüsü sertifikayı taşırdı ve üç kişi şifreyi bilirdi çünkü birinin şifreyi döndürmesi gerekiyordu. Geri çağrıyla görüntü hiçbir sır taşımaz: pod başlangıçta bir AppRole tokenı alır, vault/sample-signer.hcl içindeki politika anahtarı okuma ve onunla imzalama izni verir, tokenın denediği başka her şey 403 permission denied döndürür.

Denetçi, Mart ayında kaç belgenin imzalandığını ve hangi anahtar sürümüyle olduğunu sorduğunda, cevap uygulama günlüklerinden değil Vault’un denetim cihazından gelir.

Döndürme, bu tasarımın değer kazandığı ve aynı zamanda sorun yaratabileceği yerdir. transit/keys/:name/rotate işleminden sonra Vault, aksi belirtilmedikçe en yeni sürümle imzalar; bu yüzden sürüm 1 için oluşturulmuş bir sertifika, sürüm 2 imzası ile birleştirildiğinde hata raporlamayan ve doğrulanamayan bir PDF ortaya çıkar. İmzalayan tek bir sürümle oluşturulduğu için bu burada tesadüfen gerçekleşemez: bildirim servisi, sertifikasının ait olduğu sürümle imzalamaya devam eder, birisi yeni sürüm için yeni bir sertifika yayınlayana kadar. Anahtar üzerinde min_encryption_version ayarlandığında eski sürüm kullanılamaz hâle gelir; Vault bunu kötü bir imza olarak değil, imzalamayı reddetme olarak raporlar.

26.10 sürümünde hangi tuhaflıkları beklemeliyim?

Dört adet, hepsi bu derleme çalıştırılırken bulundu. ICustomSignHash metod adı jar içinde karıştırılmıştır, bu yüzden arayüzü uygulamak yerine bir metod referansı geçirin. İmzalı çıktı, imzanın dışında sıfır baytlarla gelir, bu yüzden onları kesin. DigitalVerifyOptions bir akış değil bir sertifika dosyası ister. Ve görünen imza kutusunun Arial yüklü olmasını gerektirir.

GroupDocs.Signature ile Başka Ne Yapabilirsiniz?

Geri çağrının arkasında ne olduğu bilinmez, bu yüzden aynı üç adım bir donanım modülü, bir akıllı kart veya bir bulut KMS karşısında da çalışır. Bunu aynı örnekten .NET ve Python sürümlerinden port ettim ve Vault istek gövdesi değişmeden geldi; sertifika oluşturma ve bu dört tuhaflık gerçek anlamda yalnızca Java’ya özgü bölümlerdir. Dijital imzaların ötesinde kütüphane PDF, Word, Excel, PowerPoint ve görüntü formatları üzerinde metin, resim, barkod, QR kod ve metadata imzaları ekleyip arama yapabilir.

Sonuç

Java’da özel anahtar tutmadan bir PDF imzalamak bir geri çağrı, genel anahtar etrafında oluşturulmuş bir sertifika ve iki yetkiye sahip bir token gerektirir. Örnek, iki komutla bir dev-mod Vault’a karşı çalışır ve aynı kod VAULT_ADDR ve VAULT_TOKEN değerleri değiştirilerek üretim Vault’una yönlendirilir.

Ek Kaynaklar