💡 דוגמה מלאה עובדת זמינה ב‑GitHub:
sign-pdf-with-vault-managed-key-java
הדרך הישנה הייתה כואבת
ספר ההפעלה של שירות חתימה ב‑Java נוטה לכלול שלב שאף אחד לא אוהב לכתוב: להעתיק
signing.pfx למארח החדש, ואז לשים את הסיסמה במשתנה סביבתי. מהרגע הזה המפתח הפרטי קיים
בפחות משלוש מקומות נוספים ממה שהתכוונו. הוא נמצא בשכבת התמונה, בגיבוי של המארח,
ובזיכרון של ה‑JVM שמטען אותו, שם דחיפת ערמת זיכרון (heap dump) תציג אותו לכל מי שיש לו את
הדחיפה.
חתימה חיצונית היא יכולת של GroupDocs.Signature עבור Java שמעבירה את תקציר המסמך לקריאת‑חזרה (callback) שאתה מספק במקום לחתום עם מפתח פרטי שהיישום טוען. זה החלק שמאפשר למחוק את שלב ספר ההפעלה הזה. מפתח החתימה מועבר ל‑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
מתקבל בכ-15 שורות.
@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.
לאחר מכן מאמתים לפני שהקובץ הולך לשום מקום. חתימה ואימות בריצה אחת הוא מה שהופך את מצב הכשל השקט היחיד למצב כשל מיידי.
השוואה ציד-ציד: לפני vs. אחרי
| PFX על המארח | קריאת‑חזרה של Vault Transit | |
|---|---|---|
| עותקים של המפתח הפרטי | אחד לכל מארח, תמונה וגיבוי | אחד, בתוך Vault |
| מה שהשירות מחזיק | המפתח והסיסמה שלו | אסימון עם שני פעולות |
| שלב פריסה למארח חדש | העתקת ה‑PFX, הגדרת הסיסמה | אין |
| רישום של כל חתימה | יומני יישום, אם נכתבו | ערך ביקורת אחד ב‑Vault |
| אחרי חשד לדליפה | שלילה, הוצאה מחדש, פריסה מחדש בכל מקום | סיבוב ב‑Vault, הוצאה מחדש פעם אחת |
| מי יכול לחתום במקומך | כל מי שיש לו את הקובץ והסיסמה | כל מי שיש לו אסימון Vault תקף |
השורה האחרונה ראויה לציון במפורש: זה מעביר את הסוד במקום לחסל אותו. ההבדל הוא שאסימון קצר‑חיים, ניתן לביטול במקום אחד, מוגבל לקריאת מפתח אחד בלבד ולקריאת‑חזרה של חתימה, ומתווסף לכל שימוש.
דוגמה מהעולם האמיתי: שירות הצהרות
שירות מייצר הצהרות חודשיות וחותם כל אחת לפני שמכניס אותה לפורטל הלקוח.
במערכת הישנה תמונת המכולה נשאה את האישור, ושלושה אנשים ידעו את הסיסמה כי מישהו
היה צריך לסובב אותה. עם קריאת‑החזרה, התמונה אינה נושאת סוד כלל: הפוד מקבל אסימון
AppRole בעת ההפעלה, המדיניות ב‑vault/sample-signer.hcl מאפשרת קריאת המפתח וחתימה
בוא, וכל ניסיון אחר של האסימון מחזיר 403 permission denied.
כאשר המבקר שואל כמה מסמכים נחתמו במרץ ובאילו גרסאות מפתח, התשובה מגיעה ממכשיר הביקורת של Vault במקום מחיפוש ביומני היישום.
הסיבוב הוא המקום שבו העיצוב הזה מרוויח את מקומו, וגם המקום שבו הוא עלול ללעוס.
לאחר 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 בייצור על‑ידי שינוי VAANT_ADDR ו‑VAULT_TOKEN.