💡 ตัวอย่างทำงานเต็มที่พร้อมบน GitHub: sign-pdf-with-vault-managed-key-java
วิธีเดิมทำให้เจ็บปวด
คู่มือการทำงานของบริการเซ็น Java มักมีขั้นตอนที่ไม่มีใครอยากเขียนลงไป: คัดลอก signing.pfx ไปยังโฮสต์ใหม่ แล้วใส่รหัสผ่านใน environment จากนั้นกุญแจส่วนตัวจะปรากฏอยู่ในอย่างน้อยสามที่เพิ่มเติมจากที่ตั้งใจไว้ มันอยู่ในชั้นของอิมเมจ, ในสำเนาสำรองของโฮสต์, และในหน่วยความจำของ JVM ที่โหลดมัน ซึ่งการดัมพ์ heap จะโชว์ให้ผู้ที่มีดัมพ์เห็นได้อย่างง่ายดาย
การเซ็นภายนอกเป็นความสามารถของ GroupDocs.Signature สำหรับ Java ที่ส่งค่า digest ของเอกสารไปยัง callback ที่คุณให้แทนการเซ็นด้วยกุญแจส่วนตัวที่แอปพลิเคชันโหลด มันเป็นส่วนที่ทำให้คุณลบขั้นตอนในคู่มือออกได้ กุญแจเซ็นย้ายเข้าไปใน HashiCorp Vault, บริการเก็บ token แทนกุญแจ, และค่าที่ส่งผ่านสายระหว่างการเซ็นมีเพียงแฮชขนาด 32 ไบต์เท่านั้น
ทีมต่าง ๆ มักใช้วิธีนี้เมื่อการตรวจสอบถามคำถามที่ชัดเจน – ใครอีกคนที่สามารถเซ็นในนามของคุณได้ – และคำตอบที่ซื่อสัตย์คือ “ใครก็ตามที่เคยเข้าถึงไฟล์นั้น” การล็อกไฟล์ด้วยสิทธิ์และโวลุ่มที่เข้ารหัสอาจจำกัดช่วงเวลาได้ แต่ไม่ได้ลบสำเนาออก
มีวิธีที่ดีกว่า
Vault’s Transit engine ทำงานด้านการเข้ารหัสเป็นบริการ คุณส่งค่าให้มัน, มันเซ็นด้วยกุญแจที่ถืออยู่, แล้วคืนผลลัพธ์ กุญแจที่สร้างภายใน Transit สามารถทำเครื่องหมายว่าไม่สามารถส่งออกได้, ดังนั้นจึงไม่มีอะไรต้องคัดลอกไปยังโฮสต์ตั้งแต่แรก, และ Vault ไม่ได้เก็บสิ่งที่คุณส่งให้มัน
สิ่งนี้ช่วยได้เฉพาะเมื่อไลบรารีการเซ็นสามารถมอบหมายได้, ซึ่งเป็นจุดที่ GroupDocs.Signature เข้ามา DigitalSignOptions.setCustomSignHash รับ callback ไลบรารีทำทุกอย่างจนถึงขั้นการเข้ารหัส: เปิด PDF, คำนวณช่วงไบต์ที่ลายเซ็นครอบคลุม, แฮช, เรียก callback ของคุณพร้อม digest, แล้วฝังไบต์ที่ได้กลับไปพร้อมกับใบรับรอง
คุณต้องมี JDK 8 หรือใหม่กว่า, Maven, Docker สำหรับ Vault ภายในเครื่อง, และ BouncyCastle สำหรับใบรับรอง ตัวอย่างทำงานกับ GroupDocs.Signature for Java 26.10; หากไม่มีไลเซนส์, โหมดประเมินจะรับเอกสารได้สูงสุด 2 หน้า
วิธีใหม่: Callback แทนไฟล์กุญแจ
ขั้นตอนที่ 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 และสร้างกุญแจล่วงหน้า, และ token ของแอปพลิเคชันจะไม่ได้รับอนุญาตให้ทำอย่างใดอย่างหนึ่ง
อ่านเวอร์ชันครั้งเดียวและเก็บไว้ ใบรับรองมีเพียงกุญแจสาธารณะหนึ่งตัว, ดังนั้นใบรับรองและลายเซ็นทุกอันต้องมาจากเวอร์ชันเดียวกัน
ขั้นตอนที่ 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 เขียนไบต์ที่ต้องเซ็นลงในสตรีมของ signer แล้วขอลายเซ็น ไบต์จะถูกแฮชในเครื่องและเพียง digest เท่านั้นที่ส่งไปยัง Vault อินเทอร์เฟซไม่ได้ประกาศ checked exceptions, ดังนั้นความล้มเหลวของ 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()));
ภายใน callback digest จะถูกส่งไปยัง transit/sign พร้อมสองฟิลด์ที่กำหนดว่าผลลัพธ์จะเป็นที่ยอมรับหรือไม่: prehashed = true เนื่องจากอินพุตเป็นแฮชแล้ว, และ signature_algorithm = pkcs1v15 เนื่องจาก Vault ปกติใช้ PSS สำหรับกุญแจ RSA ในขณะที่ลายเซ็น PDF ต้องเป็น sha256WithRSAEncryption
จากนั้นตรวจสอบก่อนไฟล์จะถูกส่งไปที่ใด ๆ การเซ็นและตรวจสอบในรันเดียวกันเป็นสิ่งที่ทำให้โหมดความล้มเหลวเงียบเปลี่ยนเป็นโหมดที่ทันที
เปรียบเทียบ: ก่อน vs. หลัง
| PFX บนโฮสต์ | Callback ของ Vault Transit | |
|---|---|---|
| สำเนาของกุญแจส่วนตัว | หนึ่งสำเนาต่อโฮสต์, อิมเมจและสำรอง | หนึ่งสำเนา, อยู่ภายใน Vault |
| สิ่งที่บริการถือ | กุญแจและรหัสผ่านของมัน | token ที่จำกัดให้ทำสองการดำเนินการ |
| ขั้นตอนการปรับใช้โฮสต์ใหม่ | คัดลอก PFX, ตั้งรหัสผ่าน | ไม่มี |
| บันทึกของแต่ละลายเซ็น | บันทึกของแอปพลิเคชัน, หากมีการเขียน | รายการ audit ของ Vault หนึ่งรายการ |
| หลังจากสงสัยว่ามีการรั่วไหล | ยกเลิก, ออกใหม่, ปรับใช้ใหม่ทุกที่ | หมุนเวอร์ชันใน Vault, ออกใหม่ครั้งเดียว |
| ใครสามารถเซ็นในนามของคุณ | ใครก็ตามที่มีไฟล์และรหัสผ่าน | ใครก็ตามที่มี token ของ Vault ที่ถูกต้อง |
แถวสุดท้ายควรบอกอย่างตรงไปตรงมา: วิธีนี้ย้ายความลับแทนการทำลายมัน ความแตกต่างคือ token มีอายุสั้น, สามารถยกเลิกได้ในที่เดียว, จำกัดการอ่านกุญแจหนึ่งตัวและการเรียก sign, และบันทึกทุกครั้งที่ใช้
ตัวอย่างจากโลกจริง: บริการแสดงรายการ
บริการหนึ่งสร้างรายการรายเดือนและเซ็นแต่ละรายการก่อนวางลงในพอร์ทัลลูกค้า ด้วยการจัดการแบบเดิมอิมเมจคอนเทนเนอร์จะบรรจุใบรับรอง, และสามคนจะมีรหัสผ่านเพราะต้องมีคนหมุนรหัสผ่านนั้น ด้วย callback อิมเมจจะไม่มีความลับเลย: pod จะรับ token AppRole ตอนเริ่มต้น, นโยบายใน vault/sample-signer.hcl อนุญาตให้อ่านกุญแจและเซ็นด้วยมัน, และสิ่งอื่นใดที่ token พยายามทำจะคืน 403 permission denied
เมื่อผู้ตรวจสอบถามว่ามีเอกสารกี่ฉบับที่เซ็นในเดือนมีนาคมและใช้เวอร์ชันกุญแจใด คำตอบจะมาจากอุปกรณ์ audit ของ Vault แทนการ grep บันทึกแอปพลิเคชัน
การหมุนเวอร์ชันเป็นจุดที่การออกแบบนี้คุ้มค่า, แต่ก็อาจเป็นจุดที่ทำให้เกิดปัญหา หลังจาก transit/keys/:name/rotate Vault จะเซ็นด้วยเวอร์ชันใหม่สุดถ้าคุณไม่ได้บอกอย่างอื่น, ดังนั้นใบรับรองที่สร้างจากเวอร์ชัน 1 ร่วมกับลายเซ็นจากเวอร์ชัน 2 จะให้ PDF ที่ไม่แสดงข้อผิดพลาดแต่ไม่ผ่านการตรวจสอบ เนื่องจาก signer ถูกสร้างด้วยเวอร์ชันเดียว, สิ่งนี้จึงไม่เกิดขึ้นโดยบังเอิญ: บริการแสดงรายการจะเซ็นต่อไปด้วยเวอร์ชันที่ใบรับรองของมันสังกัดจนกว่าจะมีการออกใบรับรองใหม่สำหรับเวอร์ชันใหม่ การตั้งค่า min_encryption_version บนกุญแจหลังจากนั้นทำให้เวอร์ชันเก่าใช้ไม่ได้, Vault จะรายงานว่าไม่ยอมเซ็นแทนที่จะเป็นลายเซ็นที่ผิดพลาด
ควรคาดหวังข้อแปลกประหลาดอะไรบ้างในเวอร์ชัน 26.10?
สี่ประการ, ทั้งหมดพบขณะรันบิลด์นี้ วิธี ICustomSignHash ถูกทำให้เป็นชื่อที่สับสนใน jar, ดังนั้นให้ส่งอ้างอิงเมธอดแทนการ implement อินเทอร์เฟซ ผลลัพธ์ที่เซ็นจะมาพร้อมไบต์ศูนย์ต่อท้ายนอกลายเซ็น, ดังนั้นต้องตัดออก DigitalVerifyOptions ต้องการไฟล์ใบรับรอง, ไม่ใช่สตรีม, และกล่องลายเซ็นที่มองเห็นได้ต้องมี Arial ติดตั้ง
อีกอะไรที่คุณทำได้กับ GroupDocs.Signature?
Callback ไม่รู้ว่าอะไรอยู่เบื้องหลัง, ดังนั้นสามขั้นตอนเดียวกันทำงานกับโมดูลฮาร์ดแวร์, สมาร์ทการ์ด หรือคลาวด์ KMS ฉันได้พอร์ตตัวอย่างนี้จากเวอร์ชัน .NET และ Python ของตัวอย่างเดียวกัน, และ body ของคำขอ Vault มาถึงโดยไม่เปลี่ยนแปลง; การสร้างใบรับรองและสี่ข้อแปลกประหลาดเหล่านี้เป็นส่วนที่เป็น Java จริง ๆ เท่านั้น นอกเหนือจากลายเซ็นดิจิทัล ไลบรารียังเพิ่มและค้นหาลายเซ็นข้อความ, รูปภาพ, บาร์โค้ด, QR code และเมตาดาต้าบน PDF, Word, Excel, PowerPoint และรูปแบบภาพต่าง ๆ
สรุป
การเซ็น PDF ใน Java โดยไม่ถือกุญแจส่วนตัวต้องใช้ callback, ใบรับรองที่สร้างจากกุญแจสาธารณะ, และ token ที่มีสองสิทธิ์ ตัวอย่างทำงานกับ Vault โหมด dev ด้วยสองคำสั่ง, และโค้ดเดียวกันสามารถชี้ไปที่ Vault การผลิตได้โดยเปลี่ยน VAULT_ADDR และ VAULT_TOKEN