💡 مثال کامل قابل اجرا در گیت‌هاب موجود است:
sign-pdf-with-vault-managed-key-java

روش قدیمی دردناک بود

دفترچه راهنمای یک سرویس امضای Java معمولاً شامل مرحله‌ای است که هیچ‌کس دوست ندارد آن را بنویسد: کپی کردن signing.pfx به سرور جدید، سپس قرار دادن رمز عبور در محیط. از همان لحظه کلید خصوصی در حداقل سه مکان بیشتر از آنچه کسی قصد داشته وجود دارد. این کلید در لایه تصویر، در نسخه پشتیبان سرور و در حافظه JVM که آن را بارگذاری می‌کند، قرار دارد؛ جایی که یک heap dump به راحتی آن را به هر کسی که dump را دارد نشان می‌دهد.

امضای خارجی یک قابلیت GroupDocs.Signature برای Java است که digest سند را به یک callback که شما فراهم می‌کنید می‌سپارد به جای امضا کردن با کلید خصوصی که برنامه بارگذاری می‌کند. این بخش است که به شما اجازه می‌دهد آن مرحلهٔ دفترچه راهنما را حذف کنید. کلید امضا به HashiCorp Vault منتقل می‌شود، سرویس به جای کلید یک توکن نگه می‌دارد، و تنها مقداری که در طول امضا از طریق شبکه عبور می‌کند یک هش ۳۲ بایتی است.

تیم‌ها وقتی که یک بازبینی سؤال واضحی می‌پرسد – «چه کسی دیگر می‌تواند به نام شما امضا کند؟» – به این راه حل روی می‌آورند و پاسخ صادقانه این است: «هر کسی که تا به حال به آن فایل دسترسی داشته». قفل کردن فایل با مجوزها و یک حجم رمزگذاری‌شده بازهٔ زمانی را محدود می‌کند؛ اما کپی را حذف نمی‌کند.

راه بهتر وجود دارد

موتور Transit در Vault رمزنگاری را به‌عنوان سرویس ارائه می‌دهد. شما یک مقدار می‌فرستید، Vault با کلیدی که در اختیار دارد آن را امضا می‌کند و نتیجه را برمی‌گرداند. کلیدی که داخل Transit ایجاد می‌شود می‌تواند به‌صورت non‑exportable علامت‌گذاری شود، بنابراین در ابتدا چیزی برای کپی کردن روی سرور وجود ندارد و Vault چیزی که شما می‌فرستید را ذخیره نمی‌کند.

این فقط زمانی مفید است که کتابخانهٔ امضا بتواند واگذاری کند، که اینجاست که GroupDocs.Signature وارد می‌شود. DigitalSignOptions.setCustomSignHash یک callback می‌گیرد. کتابخانه تمام کارها را تا مرحلهٔ رمزنگاری انجام می‌دهد: PDF را باز می‌کند، بازهٔ بایتی که امضا پوشش می‌دهد را محاسبه می‌کند، آن را هش می‌کند، callback شما را با digest صدا می‌زند، سپس هر بایتی که برگردانده می‌شود را همراه با گواهی‌نامه درون‌گذاری می‌کند.

به JDK 8 یا بالاتر، Maven، Docker برای یک Vault محلی و BouncyCastle برای گواهی‌نامه نیاز دارید. این نمونه با GroupDocs.Signature برای Java نسخه 26.10 اجرا می‌شود؛ بدون لایسنس، حالت ارزیابی اسناد حداکثر ۲ صفحه را می‌پذیرد.

روش جدید: یک Callback به‌جای فایل کلید

گام ۱ – خواندن کلید از Vault

سرویس از Vault می‌پرسد که کلیدی که مجاز به استفاده از آن است چیست و یک شماره نسخه به همراه کلید عمومی برمی‌گرداند. نصف خصوصی هرگز در پاسخ وجود ندارد.

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

یک ۴۰۴ از Vault به این معنی است که یا کلید یا mount Transit موجود نیست، بنابراین نمونه آن را به‌عنوان تنظیمات اولین اجرا در نظر می‌گیرد نه به‌عنوان خطا. در محیط تولید یک مدیر Transit را فعال می‌کند و کلید را از پیش ایجاد می‌کند و توکن برنامه اجازهٔ انجام هیچ‌یک از این کارها را ندارد.

نسخه را یک‌بار بخوانید و نگه دارید. یک گواهی‌نامه دقیقاً یک کلید عمومی دارد، بنابراین گواهی‌نامه و هر امضایی باید از همان نسخه باشند.

گام ۲ – ساخت گواهی‌نامه‌ای دور کلید عمومی

یک امضای 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 بایت‌های قابل امضا را در جریان امضاکننده می‌نویسد و سپس درخواست امضا را می‌دهد. بایت‌ها به‌صورت محلی هش می‌شوند و فقط digest به Vault می‌رود. این رابط هیچ استثنای checked‌ای اعلام نمی‌کند، بنابراین شکست Vault باید به‌صورت بسته شده به فراخواننده برگردد؛ اگر این کار را نادیده بگیرید، یک ۴۰۳ از Vault به‌عنوان خطای زمان اجرا مبهم ظاهر می‌شود.

گام ۳ – امضا، سپس تأیید در همان اجرا

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 به‌صورت پیش‌فرض برای کلیدهای RSA از PSS استفاده می‌کند در حالی که یک امضای PDF نیاز به sha256WithRSAEncryption دارد.

سپس قبل از اینکه فایل به جایی برود، تأیید کنید. امضا و تأیید در یک اجرا همان چیزی است که حالت شکست ساکت را به یک شکست فوری تبدیل می‌کند.

مقایسهٔ کنار هم: قبل vs. بعد

PFX روی سرور Callback Transit Vault
کپی‌های کلید خصوصی یک‌بار برای هر سرور، تصویر و نسخه پشتیبان یک‌بار، داخل Vault
آنچه سرویس نگه می‌دارد کلید و رمز عبور آن یک توکن با دو عملیات محدود
گام استقرار برای سرور جدید کپی PFX، تنظیم رمز عبور هیچ‌چیز
رکورد هر امضا لاگ‌های برنامه، اگر نوشته شوند یک ورودی audit در Vault
پس از یک نشت مشکوک لغو، صدور مجدد، استقرار مجدد در همه جا چرخش در Vault، صدور مجدد یک‌بار
چه کسی می‌تواند به نام شما امضا کند هر کسی که فایل و رمز عبور را داشته باشد هر کسی که توکن معتبر Vault داشته باشد

سطر آخر ارزش بیان واضح دارد: این روش راز را جابه‌جا می‌کند نه اینکه آن را از بین ببرد. تفاوت این است که توکن کوتاه‌مدت، قابل لغو در یک مکان، محدود به خواندن یک کلید و فراخوانی sign است و هر بار استفاده‌شده ثبت می‌شود.

مثال واقعی: سرویس صورت‌حساب

یک سرویس صورت‌حساب ماهانه تولید می‌کند و هر یک را قبل از قرار دادن در پرتال مشتری امضا می‌کند. با تنظیمات قدیمی تصویر کانتینر گواهی‌نامه را حمل می‌کرد و سه نفر رمز عبور را داشتند چون کسی باید آن را چرخاند. با callback، تصویر هیچ رازیتی ندارد: پاد در زمان راه‌اندازی یک توکن AppRole دریافت می‌کند، سیاست موجود در vault/sample-signer.hcl اجازهٔ خواندن کلید و امضا با آن را می‌دهد و هر کاری که توکن سعی کند انجام دهد 403 permission denied برمی‌گرداند.

وقتی حسابرس می‌پرسد چند سند در ماه مارس امضا شده و با کدام نسخه کلید، پاسخ از دستگاه audit Vault می‌آید نه از جستجوی لاگ‌های برنامه.

چرخش جایی است که این طراحی ارزش خود را نشان می‌دهد و همچنین می‌تواند مشکل‌ساز باشد. پس از transit/keys/:name/rotate Vault با جدیدترین نسخه امضا می‌کند مگر این که خلاف آن را بگویید، بنابراین گواهی‌نامه‌ای ساخته‌شده برای نسخه ۱ همراه با امضایی از نسخه ۲ یک PDF تولید می‌کند که هیچ خطایی گزارش نمی‌دهد و تأیید نمی‌شود. چون امضاکننده با یک نسخه ساخته می‌شود، این اتفاق نمی‌افتد: سرویس صورت‌حساب تا زمانی که گواهی‌نامه جدیدی برای نسخه جدید صادر نشود، با نسخه‌ای که گواهی‌نامه‌اش به آن تعلق دارد ادامه می‌دهد. تنظیم min_encryption_version روی کلید پس از آن، نسخهٔ قدیمی را غیرقابل استفاده می‌کند؛ Vault این را به‌عنوان رد امضا نه به‌عنوان امضای بد گزارش می‌دهد.

چه نکات عجیبی در نسخه 26.10 باید انتظار داشته باشم؟

چهار مورد که همه در حین اجرای این ساختار پیدا شدند. نام متد ICustomSignHash در jar مخفی شده است، بنابراین به‌جای پیاده‌سازی اینترفیس، یک مرجع متد پاس دهید. خروجی امضا شده با بایت‌های صفر در انتهای خارج از امضا می‌آید، بنابراین آن‌ها را برش دهید. DigitalVerifyOptions به یک فایل گواهی‌نامه نیاز دارد، نه یک جریان. و جعبهٔ امضای قابل مشاهده به Arial نصب‌شده نیاز دارد.

دیگر چه کارهایی می‌توانید با GroupDocs.Signature انجام دهید؟

Callback نمی‌داند پشت سرش چه چیزی است، بنابراین همان سه گام می‌توانند علیه یک ماژول سخت‌افزاری، یک کارت هوشمند یا یک KMS ابری کار کنند. این نمونه را از نسخه‌های .NET و Python همان نمونه منتقل کرده‌ام و بدنهٔ درخواست Vault بدون تغییر باقی مانده؛ ساخت گواهی‌نامه و آن چهار نکته تنها بخش‌های واقعی جاوا‑محور هستند. علاوه بر امضاهای دیجیتال، کتابخانه همچنین متن، تصویر، بارکد، QR code و امضاهای متادیتا را در PDF، Word، Excel، PowerPoint و فرمت‌های تصویری جستجو و اضافه می‌کند.

نتیجه‌گیری

امضای یک PDF در Java بدون نگهداری کلید خصوصی نیاز به یک callback، یک گواهی‌نامه ساخته‌شده دور یک کلید عمومی و یک توکن با دو حق دارد. این نمونه در یک Vault حالت توسعه با دو فرمان اجرا می‌شود و همان کد با تغییر VAANT_ADDR و VAULT_TOKEN به یک Vault تولیدی اشاره می‌کند.

منابع تکمیلی