💡 مثال كامل يعمل متاح على GitHub:
توقيع‑PDF‑باستخدام‑مفتاح‑مدار‑من‑Vault‑Java
الطريقة القديمة كانت مؤلمة
دليل التشغيل لخدمة توقيع Java يميل إلى احتواء خطوة لا يحب أحد كتابتها: نسخ signing.pfx إلى المضيف الجديد، ثم وضع كلمة المرور في البيئة. من تلك اللحظة يصبح المفتاح الخاص موجودًا في ثلاثة أماكن على الأقل أكثر مما كان مقصودًا. إنه في طبقة الصورة، وفي نسخة احتياطية للمضيف، وفي ذاكرة JVM التي تحمله، حيث سيظهر تفريغ الذاكرة (heap dump) المفتاح لأي شخص يمتلك التفريغ.
التوقيع الخارجي هو قدرة GroupDocs.Signature لـ Java تُسلم ملخص المستند إلى رد نداء (callback) تقدمه بدلاً من التوقيع باستخدام مفتاح خاص يحملها التطبيق. هذه هي القطعة التي تسمح لك بحذف خطوة دليل التشغيل تلك. ينتقل مفتاح التوقيع إلى HashiCorp Vault، وتحتفظ الخدمة برمز (token) بدلاً من المفتاح، والقيمة الوحيدة التي تعبر السلك أثناء التوقيع هي تجزئة بطول 32 بايت.
تتجه الفرق إلى هذا عندما يطرح المراجعة السؤال الواضح - من يمكنه التوقيع نيابةً عنك - والإجابة الصادقة هي “أي شخص كان لديه حق الوصول إلى ذلك الملف”. قفل الملف بالأذونات وحجم مشفر يضيق النافذة؛ لكنه لا يزيل النسخة.
هناك طريقة أفضل
محرك Transit في Vault يقوم بالتشفير كخدمة. ترسل له قيمة، وهو يوقعها بمفتاح يحتفظ به، ثم يعيد النتيجة. يمكن وضع علامة على المفتاح الذي يُنشأ داخل Transit بأنه غير قابل للتصدير، لذا لا يوجد شيء لنسخه إلى مضيف في المقام الأول، ولا يخزن Vault ما ترسله إليه.
هذا لا يساعد إلا إذا كانت مكتبة التوقيع تستطيع التفويض، وهذا هو المكان الذي تأتي فيه GroupDocs.Signature. DigitalSignOptions.setCustomSignHash يأخذ رد نداء. تقوم المكتبة بكل شيء حتى التشفير: تفتح ملف PDF، تحسب نطاق البايتات الذي يغطيه التوقيع، تقوم بتجزئته، تستدعي رد نداءك مع التجزئة، ثم تُدمج أي بايتات تعود مع الشهادة.
تحتاج إلى JDK 8 أو أحدث، Maven، Docker لـ Vault محلي، وBouncyCastle للشهادة. يعمل العينة مع GroupDocs.Signature لـ Java 26.10؛ بدون ترخيص، وضع التقييم يقبل مستندات تصل إلى صفحتين.
الطريقة الجديدة: رد نداء بدلاً من ملف المفتاح
الخطوة 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 يتكون من حوالي خمس عشرة سطرًا.
@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. الواجهة لا تُعلن عن استثناءات checked، لذا يجب أن يُغلف فشل Vault ويُفكّغ من قبل المستدعي؛ إذا تخطيت ذلك يظهر خطأ تشغيل محير عندما يُرجع Vault رمز 403.
الخطوة 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.
ثم تحقق قبل أن ينتقل الملف إلى أي مكان. التوقيع والتحقق في تشغيل واحد هو ما يحول وضع الفشل الصامت الوحيد إلى فشل فوري.
جنبًا إلى جنب: قبل مقابل بعد
| PFX على المضيف | رد نداء Vault Transit | |
|---|---|---|
| نسخ المفتاح الخاص | واحد لكل مضيف، صورة ونسخة احتياطية | واحد، داخل Vault |
| ما الذي تحتفظ به الخدمة | المفتاح وكلمة مروره | رمز مخصص لعمليتين |
| خطوة النشر لمضيف جديد | نسخ الـ PFX، تعيين كلمة المرور | لا شيء |
| سجل كل توقيع | سجلات التطبيق، إذا تم كتابتها | إدخال تدقيق واحد في Vault |
| بعد تسرب مشتبه به | إلغاء، إعادة إصدار، إعادة نشر في كل مكان | تدوير في Vault، إعادة إصدار مرة واحدة |
| من يمكنه التوقيع نيابةً عنك | أي شخص لديه الملف وكلمة المرور | أي شخص لديه رمز Vault صالح |
الصف الأخير يستحق الذكر صراحةً: هذا ينقل السر بدلاً من إلغائه. الفرق هو أن الرمز قصير العمر، قابل للإلغاء في مكان واحد، محدود بقراءة مفتاح واحد واستدعاء sign، ويسجل كل مرة يُستخدم فيها.
مثال واقعي: خدمة كشف حسابات
تقوم خدمة بإنتاج كشوف حساب شهرية وتوقع كل واحدة قبل وضعها في بوابة العملاء. مع الترتيب القديم كانت صورة الحاوية تحمل الشهادة، وكان ثلاثة أشخاص يمتلكون كلمة المرور لأن أحدهم كان يجب أن يديرها. مع رد النداء، لا تحمل الصورة أي سر على الإطلاق: يحصل الـ pod على رمز 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 إنتاجي بتغيير VAULT_ADDR وVAULT_TOKEN.