💡 Contoh lengkap yang berfungsi tersedia di GitHub: sign-pdf-with-vault-managed-key-java

Cara Lama Sangat Menyakitkan

Buku panduan untuk layanan penandatanganan Java cenderung berisi langkah yang tidak disukai siapa pun untuk dituliskan: menyalin signing.pfx ke host baru, lalu menaruh kata sandi di lingkungan. Sejak saat itu kunci pribadi berada di setidaknya tiga tempat lagi selain yang diharapkan. Kunci tersebut berada di lapisan image, di cadangan host, dan di memori JVM yang memuatnya, di mana dump heap akan dengan senang hati menampilkannya kepada siapa pun yang memiliki dump tersebut.

Penandatanganan eksternal adalah kemampuan GroupDocs.Signature untuk Java yang menyerahkan digest dokumen ke callback yang Anda sediakan alih-alih menandatangani dengan kunci pribadi yang dimuat aplikasi. Ini adalah bagian yang memungkinkan Anda menghapus langkah buku panduan tersebut. Kunci penandatanganan dipindahkan ke HashiCorp Vault, layanan menyimpan token alih-alih kunci, dan satu-satunya nilai yang melintasi jaringan selama penandatanganan adalah hash 32‑byte.

Tim beralih ke ini ketika tinjauan menanyakan pertanyaan yang jelas – siapa lagi yang dapat menandatangani atas nama Anda – dan jawaban jujurnya adalah “siapa saja yang pernah memiliki akses ke file itu”. Mengunci file dengan izin dan volume terenkripsi mempersempit jendela; itu tidak menghilangkan salinan.

Ada Cara yang Lebih Baik

Mesin Transit Vault melakukan kriptografi sebagai layanan. Anda mengirimkan nilai, ia menandatangani dengan kunci yang dimilikinya, dan mengembalikan hasilnya. Kunci yang dibuat di dalam Transit dapat ditandai tidak dapat diekspor, sehingga tidak ada yang perlu disalin ke host sejak awal, dan Vault tidak menyimpan apa yang Anda kirimkan.

Itu hanya membantu jika perpustakaan penandatanganan dapat mendelegasikan, di sinilah GroupDocs.Signature berperan. DigitalSignOptions.setCustomSignHash menerima sebuah callback. Perpustakaan melakukan semua hal hingga kriptografi: membuka PDF, menghitung rentang byte yang ditandatangani, meng-hash‑nya, memanggil callback Anda dengan digest, lalu menyematkan byte apa pun yang kembali bersama sertifikat.

Anda memerlukan JDK 8 atau lebih baru, Maven, Docker untuk Vault lokal, dan BouncyCastle untuk sertifikat. Contoh ini berjalan dengan GroupDocs.Signature untuk Java 26.10; tanpa lisensi, mode evaluasi menerima dokumen hingga 2 halaman.

Cara Baru: Callback Alih-alih File Kunci

Langkah 1 - Baca kunci dari Vault

Layanan meminta Vault kunci yang diizinkan untuk digunakan dan mendapatkan nomor versi dengan kunci publik. Setengah pribadi tidak pernah ada dalam respons.

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

404 dari Vault berarti baik kunci maupun mount Transit tidak ada, sehingga contoh memperlakukan ini sebagai penyiapan pertama kali alih-alih kesalahan. Dalam produksi seorang administrator mengaktifkan Transit dan membuat kunci sebelumnya, dan token aplikasi tidak diizinkan melakukan keduanya.

Baca versi sekali dan simpan. Sertifikat memuat tepat satu kunci publik, sehingga sertifikat dan setiap tanda tangan harus berasal dari versi yang sama.

Langkah 2 - Bangun sertifikat di sekitar setengah publik

Tanda tangan PDF membawa sertifikat X.509 agar verifier dapat menemukan kunci publik. JDK tidak memiliki cara untuk membangun sertifikat yang tandatangannya berasal dari tempat lain, tetapi BouncyCastle dapat: X509v3CertificateBuilder mendelegasikan ke ContentSigner, dan ContentSigner yang didukung Vault terdiri dari sekitar lima belas baris.

@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 menulis byte yang akan ditandatangani ke aliran penandatangan, lalu meminta tanda tangan. Byte di‑hash secara lokal dan hanya digest yang dikirim ke Vault. Antarmuka tidak mendeklarasikan pengecualian yang diperiksa, sehingga kegagalan Vault harus dibungkus keluar dan dibuka kembali oleh pemanggil; lewati itu dan 403 dari Vault muncul sebagai kesalahan runtime yang membingungkan.

Langkah 3 - Tanda tangani, lalu verifikasi dalam satu run

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

Di dalam callback digest dikirim ke transit/sign dengan dua bidang yang menentukan apakah hasilnya valid: prehashed = true, karena input sudah berupa hash, dan signature_algorithm = pkcs1v15, karena Vault default ke PSS untuk kunci RSA sementara tanda tangan PDF adalah sha256WithRSAEncryption.

Kemudian verifikasi sebelum file pergi ke mana pun. Menandatangani dan memverifikasi dalam satu run mengubah satu‑satunya mode kegagalan diam menjadi mode kegagalan langsung.

Perbandingan: Sebelum vs. Sesudah

PFX di host Callback Vault Transit
Salinan kunci pribadi satu per host, image, dan backup satu, di dalam Vault
Apa yang dimiliki layanan kunci dan kata sandinya token dengan ruang lingkup dua operasi
Langkah penyebaran untuk host baru salin PFX, atur kata sandi tidak ada
Catatan setiap tanda tangan log aplikasi, jika ditulis satu entri audit Vault
Setelah kebocoran yang dicurigai cabut, terbitkan ulang, sebarkan ulang di mana-mana rotasi di Vault, terbitkan ulang sekali
Siapa yang dapat menandatangani atas nama Anda siapa saja yang memiliki file dan kata sandi siapa saja dengan token Vault yang valid

Baris terakhir layak dinyatakan secara jelas: ini memindahkan rahasia alih-alih menghilangkannya. Perbedaannya adalah token bersifat pendek umur, dapat dicabut di satu tempat, terbatas pada membaca satu kunci dan memanggil tanda tangan, serta tercatat setiap kali digunakan.

Contoh Dunia Nyata: Layanan Pernyataan

Sebuah layanan menghasilkan pernyataan bulanan dan menandatangani masing‑masing sebelum menaruhnya di portal pelanggan. Dengan pengaturan lama image kontainer membawa sertifikat, dan tiga orang memiliki kata sandi karena seseorang harus memutarnya. Dengan callback, image tidak membawa rahasia sama sekali: pod mendapatkan token AppRole saat startup, kebijakan di vault/sample-signer.hcl mengizinkan membaca kunci dan menandatangani dengan kunci tersebut, dan apa pun yang dicoba token menghasilkan 403 permission denied.

Ketika auditor menanyakan berapa banyak dokumen yang ditandatangani pada bulan Maret dan dengan versi kunci mana, jawabannya berasal dari perangkat audit Vault bukan dari pencarian log aplikasi.

Rotasi adalah tempat desain ini menghasilkan nilai, sekaligus tempat ia dapat menimbulkan masalah. Setelah transit/keys/:name/rotate Vault menandatangani dengan versi terbaru kecuali Anda menyatakan lain, sehingga sertifikat yang dibangun untuk versi 1 digabungkan dengan tanda tangan dari versi 2 menghasilkan PDF yang tidak melaporkan kesalahan namun tidak dapat diverifikasi. Karena penandatangan dibangun dengan satu versi, hal ini tidak dapat terjadi secara tidak sengaja di sini: layanan pernyataan terus menandatangani dengan versi yang dimiliki sertifikatnya hingga seseorang mengeluarkan sertifikat baru untuk versi baru. Menetapkan min_encryption_version pada kunci setelahnya membuat versi lama tidak dapat digunakan, yang Vault laporkan sebagai penolakan menandatangani bukan sebagai tanda tangan yang buruk.

Keanehan apa yang harus saya harapkan pada versi 26.10?

Empat, semuanya ditemukan saat menjalankan build ini. Nama metode ICustomSignHash diobfusikasi dalam jar, jadi berikan referensi metode alih-alih mengimplementasikan antarmuka. Output yang ditandatangani muncul dengan byte nol berlebih di luar tanda tangan, jadi pangkaslah. DigitalVerifyOptions menginginkan file sertifikat, bukan aliran. Dan kotak tanda tangan yang terlihat memerlukan Arial terpasang.

Apa Lagi yang Bisa Anda Lakukan dengan GroupDocs.Signature?

Callback tidak mengetahui apa yang ada di belakangnya, sehingga tiga langkah yang sama dapat bekerja terhadap modul perangkat keras, kartu pintar, atau KMS cloud. Saya memporting ini dari versi .NET dan Python dari contoh yang sama, dan badan permintaan Vault tetap tidak berubah; konstruksi sertifikat dan empat keanehan tersebut adalah satu‑satunya bagian yang benar‑benar berbentuk Java. Di luar tanda tangan digital, perpustakaan ini juga menambah dan mencari tanda tangan teks, gambar, barcode, kode QR, dan metadata di seluruh format PDF, Word, Excel, PowerPoint, dan gambar.

Kesimpulan

Menandatangani PDF dalam Java tanpa memegang kunci pribadi memerlukan callback, sertifikat yang dibangun di sekitar kunci publik, dan token dengan dua hak. Contoh ini berjalan melawan Vault mode dev dengan dua perintah, dan kode yang sama diarahkan ke Vault produksi dengan mengubah VAULT_ADDR dan VAULT_TOKEN.

Sumber Daya Tambahan