التوقيع عبر ‏KMS‏ السحابية (‏AWS KMS‏ و‏Azure Key Vault‏ و‏GCP KMS‏)

لمحة سريعة

يوقّع ⁨NextPDF Pro⁩ ملف ⁨PDF⁩ بمفتاح محفوظ في خدمة سحابية لإدارة المفاتيح (⁨KMS⁩). المزوِّدون المدعومون هم ⁨Amazon Web Services (AWS) KMS⁩ و⁨Microsoft Azure Key Vault⁩ و⁨Google Cloud Platform (GCP) Cloud KMS.⁩ ينفّذ كل مزوِّد عقد توقيع واحدًا، بحيث يعتمد تطبيقك على العقد لا على صنف المزوِّد. يُرسَل ملخّص السمات الموقَّعة فقط إلى المزوِّد؛ ولا يغادر المستند مضيفك مطلقًا في عملية التوقيع. هذه الصفحة على مستوى السلوك: تحدّد ما يرسله كل مزوِّد ويستقبله، وكيف تُحَلّ إصدارات المفاتيح، وأين تتوقّف عهدة المفاتيح عن كونها مسؤولية ⁨NextPDF.⁩

يوسّع العقد عقد المُوقِّع العتادي والسحابي في ⁨Core⁩، بحيث تندمج استراتيجية ⁨KMS⁩ السحابية في مسار التوقيع نفسه الذي يستخدمه مُوقِّع ⁨Core.⁩

المتطلّبات المسبقة محدَّدة في المقدّمة، ومكرَّرة تحت المتطلّبات المسبقة.

الإصدار والترخيص

تُشحَن استراتيجيات التوقيع عبر ⁨KMS⁩ السحابية في حزمة nextpdf/pro وتُضبَط ببوّابة علم ميزة الترخيص pro. يشحن ⁨NextPDF Core⁩ مُوقِّع ⁨CMS⁩ برمجيًا؛ ويضيف ⁨NextPDF Enterprise⁩ عهدة مفاتيح عتادية عبر ⁨PKCS#11.⁩ التوقيع عبر ⁨KMS⁩ السحابية قدرة من قدرات ⁨Pro⁩ ويمكن الوصول إليها في ⁨Enterprise⁩ أيضًا، إذ يعتمد ⁨Enterprise⁩ على ⁨Pro.⁩ لا يحمّل النشر الذي يفتقر إلى استحقاق ⁨Pro⁩ فعّال أصناف هذه الاستراتيجيات؛ ويستمرّ عقد توقيع ⁨Core⁩ في العمل من دون تغيير. قارِن الإصدارات.

ما الذي تقوم به هذه القدرة

ينفّذ كل مُوقِّع ⁨KMS⁩ سحابي عقد مزوِّد واحدًا يوسّع عقد مُوقِّع ⁨Core.⁩ يضيف العقد ثلاثة أشياء: مُعرِّف مزوِّد مستقرًّا للبحث في السجلّ، وطريقة توقيع واعية بإصدار المفتاح، ووصفًا ذاتيًا للخوارزميات التي يدعمها المزوِّد كي يتمكّن المنسِّق من اختيار مزوِّد متوافق قبل التوقيع.

يُبقي تدفّق التوقيع المستند على مضيفك:

1. تحسب جلسة توقيع ⁨Pro⁩ ملخّص المستند وتبني سمات ⁨CMS⁩ الموقَّعة.
2. تُجزِّئ الجلسة السمات الموقَّعة وترسل ذلك الملخّص فقط إلى المزوِّد. خدمة التوقيع الخارجية التي تقبل ملخّص رسالة مقدَّمًا من المُستدعِي وتعيد التوقيع هي النمط المعتمد لإبقاء المستند داخل حدودك، كما هو موصوف في الإطار المرجعي لخدمة التوقيع الرقمي في الاتحاد الأوروبي (⁨EU Digital Signature Service (DSS)⁩).
3. يوقّع المزوِّد الملخّص بإصدار المفتاح الذي يحلّه ويعيد التوقيع الخام.
4. تجمّع الجلسة ⁨CMS SignedData⁩ وتضمّنه في ملف ⁨PDF.⁩

نُفِّذ المزوِّدون عبر استدعاءات بروتوكول نقل النص الفائق (⁨Hypertext Transfer Protocol (HTTP)⁩) النقيّة وفق ⁨PSR-18⁩ — من دون أي اعتماد على حزمة تطوير برمجيات (⁨SDK⁩) من مورّد سحابي. تُفوَّض المصادقة إلى تطبيقك: فأنت تزوّد رمز حامل (⁨AWS⁩ و⁨GCP⁩) أو رمزًا أو اعتماد مدير خدمة (⁨Azure⁩). يطبّع كل مزوِّد مخرجاته من أجل ⁨CMS:⁩ يعيد ⁨AWS⁩ و⁨GCP⁩ توقيعات ⁨Rivest–Shamir–Adleman (RSA)⁩ بصيغة ⁨DER⁩ جاهزة لـ ⁨CMS؛⁩ ويُحوَّل توقيع خوارزمية التوقيع الرقمي بالمنحنى الإهليلجي (⁨Elliptic Curve Digital Signature Algorithm (ECDSA)⁩) الذي يعيده مزوِّد كزوج أعداد صحيحة خام (⁨Azure⁩) إلى الصيغة المُرمَّزة بـ ⁨DER⁩، في حين يعيد ⁨GCP⁩ توقيع ⁨ECDSA⁩ مُرمَّزًا بـ ⁨DER⁩ سلفًا. يُقرَن منحنى ⁨ECDSA⁩ وملخّصه قرنًا اعتياديًا — ⁨P-256⁩ مع ⁨SHA-256⁩، و⁨P-384⁩ مع ⁨SHA-384⁩، و⁨P-521⁩ مع ⁨SHA-512⁩ — وفق الاقتران المُوصى به في ⁨RFC 5480.⁩

يحلّ سجلّ ⁨PSR-11⁩ المزوِّدين بحسب المُعرِّف ويدعم المصانع الكسولة. يسجّل عملاء ⁨Enterprise⁩ ذاتيو الاستضافة مشغّل ⁨HSM⁩ أو ⁨KMS⁩ مملوكًا بتنفيذ عقد المزوِّد وربطه في السجلّ — من دون تشعيب ⁨NextPDF Pro.⁩

دلالات إصدار المفتاح الخاصة بكل مزوِّد

يعرض المزوِّدون أوّليّات “الإصدار الفعّال” مختلفةً، فيختلف سلوك إصدار المفتاح الافتراضي:

• ⁨AWS KMS⁩ — يستخدم إصدار المفتاح null اسمَ المفتاح المستعار، الذي يحلّه ⁨AWS⁩ إلى إصدار المفتاح الحالي على جانب المزوِّد.
• ⁨Azure Key Vault⁩ — يستخدم إصدار المفتاح null عنوان المفتاح بدون إصدار، الذي يحلّه ⁨Azure⁩ إلى أحدث إصدار مُفعَّل. ويجب أن يكون أي تجاوز صريح مُعرِّفًا ستّ عشريًا من ٣٢ محرفًا؛ وتُرفَض أي قيمة أخرى لمنع حقن مقاطع العنوان.
• ⁨GCP Cloud KMS⁩ — تعمل نقطة نهاية التوقيع غير المتماثل على إصدار مفتاح تشفير محدَّد فقط؛ فلا يوجد “إصدار فعّال” على جانب الخادم. يجب عليك تثبيت إصدار في الإعداد أو تمريره صراحةً. وفي حال عدم تعيين أيٍّ منهما، يثير المُوقِّع خطأ إدارة مفاتيح بدلًا من التخمين.

وثّق الوضع الذي يستخدمه نشرك ليكون السلوك حتميًا.

المتطلّبات المسبقة

1. ثبّت ⁨NextPDF Core⁩ وحزمة ⁨Pro⁩، واحتفظ بترخيص ⁨Pro⁩ فعّال.
2. وفّر مفتاح توقيع في المزوِّد الذي اخترته ودوّن مُعرِّفاته (اسم المفتاح المستعار أو اسم مورد ⁨Amazon⁩ لـ ⁨AWS⁩؛ والخزنة واسم المفتاح لـ ⁨Azure⁩؛ والمشروع والموقع وحلقة المفاتيح ومفتاح التشفير والإصدار لـ ⁨GCP⁩).
3. وفّر عميل ⁨HTTP⁩ وفق ⁨PSR-18⁩ ومصنعَي الطلب والتدفّق وفق ⁨PSR-17.⁩
4. احصل على اعتماد المزوِّد في تطبيقك: رمز حامل لـ ⁨AWS⁩ أو ⁨GCP⁩، أو رمزًا مُحصَّلًا مسبقًا أو اعتمادات مدير خدمة لـ ⁨Azure.⁩ تحصيل الرموز مسؤولية تطبيقك؛ وزوّد الأسرار من مدير أسرارك، لا من الشيفرة المصدرية مطلقًا.

الإعداد

لكل مزوِّد كائن إعداد غير قابل للتغيير مبنيّ من مُعرِّفاتك واعتماداتك. شواغل الإعداد المشتركة:

• مُعرِّف المزوِّد — aws-kms أو azure-keyvault أو gcp-kms، يُستخدَم مفتاح بحث في السجلّ.
• الخوارزمية — تُختار لكل استدعاء من اسم الخوارزمية الذي تمرّره جلسة توقيعك؛ ويرفض المزوِّد أي خوارزمية لا يدعمها.
• إصدار المفتاح — مثبَّت في الإعداد أو مُمرَّر لكل استدعاء، بالدلالات الخاصة بكل مزوِّد الموصوفة أعلاه.
• الاعتماد — رمز حامل أو اعتمادات مدير خدمة يزوّدها تطبيقك من مدير أسراره.

خطوة بخطوة

1. ابنِ إعداد المزوِّد من مُعرِّفاتك واعتماد مقروء من مدير أسرارك.
2. أنشئ مُوقِّع المزوِّد بالإعداد، وشهادة المُوقِّع بصيغة ⁨DER⁩، والسلسلة، وعميل ⁨PSR-18⁩، ومصانع ⁨PSR-17.⁩
3. اختياريًا سجّل المزوِّد في سجلّ ⁨PSR-11⁩ تحت مُعرِّفه ليحلّه المنسِّق بالاسم.
4. شغّل جلسة توقيع ⁨Pro:⁩ تحسب الملخّص، وتبني السمات الموقَّعة، وتستدعي المزوِّد بالملخّص فقط.
5. التقط أخصّ إخفاق — إدارة مفاتيح، أو خوارزمية غير مدعومة، أو إخفاق توقيع — وسجّل رسالة بنيوية بلا أسرار، ثم أعد رميه.

examples/pro/kms-provider-registry.php

<?php

declare(strict_types=1);

require_once __DIR__ . '/../../vendor/autoload.php';

use NextPDF\Pro\Security\Signing\Kms\KeyManagementProviderRegistry;
use NextPDF\Pro\Security\Signing\Kms\KmsSignerInterface;

/**
 * Register cloud-KMS providers behind one registry resolved by identifier.
 *
 * Each provider is supplied as a lazy factory so a provider is only
 * constructed when first resolved. The caller depends on the registry and
 * the provider contract, not on a concrete provider class.
 *
 * @param array<non-empty-string, callable(): KmsSignerInterface> $factories
 *        Provider factories keyed by provider identifier.
 *
 * @return KeyManagementProviderRegistry The populated registry.
 */
function buildKmsRegistry(array $factories): KeyManagementProviderRegistry
{
    $registry = new KeyManagementProviderRegistry();

    foreach ($factories as $providerId => $factory) {
        $registry->registerFactory($providerId, $factory);
    }

    return $registry;
}

examples/pro/kms-sign-guarded.php

<?php

declare(strict_types=1);

require_once __DIR__ . '/../../vendor/autoload.php';

use NextPDF\Pro\Security\Signing\Kms\KmsSignerInterface;
use NextPDF\Pro\Security\Exception\KeyManagementException;
use NextPDF\Pro\Security\Exception\SignatureFailedException;
use NextPDF\Pro\Security\Exception\UnsupportedAlgorithmException;
use Psr\Log\LoggerInterface;

final readonly class KmsSigningService
{
    public function __construct(
        private KmsSignerInterface $provider,
        private LoggerInterface $logger,
    ) {}

    /**
     * Sign a signed-attributes digest with a pinned key version.
     *
     * Only the digest is sent to the provider; the document stays on the
     * host. Each failure mode is caught as its most specific type so the
     * caller can distinguish a key-version problem from a transport failure.
     *
     * @param string      $digest     The signed-attributes digest to sign.
     * @param string      $algorithm  The OpenSSL-style algorithm name.
     * @param string|null $keyVersion The pinned key version, or null for the
     *                                 provider default (per-provider semantics).
     *
     * @throws KeyManagementException        When the key version is unknown or required and absent.
     * @throws UnsupportedAlgorithmException When the provider does not support the algorithm.
     * @throws SignatureFailedException      When the provider sign operation fails.
     *
     * @return string The raw signature bytes (DER for RSA and ECDSA per CMS rules).
     */
    public function sign(string $digest, string $algorithm, ?string $keyVersion): string
    {
        try {
            return $this->provider->signWithVersion($digest, $algorithm, $keyVersion);
        } catch (KeyManagementException | UnsupportedAlgorithmException | SignatureFailedException $e) {
            $this->logger->error('KMS signing failed', [
                'provider' => $this->provider->providerId(),
                'reason'   => $e->getMessage(),
            ]);

            throw $e;
        }
    }
}

التحقّق

1. أكّد أن المزوِّد يصف ذاتيًا الخوارزمية التي تنوي استخدامها قبل التوقيع، كي تُلتقَط خوارزمية غير مدعومة عند الاختيار لا عند استدعاء المزوِّد.
2. أكّد أن الملخّص وحده يُرسَل: يجب ألّا تظهر بايتات المستند في جسم طلب المزوِّد. يحمل الطلب ملخّصًا مُرمَّزًا بـ ⁨base64⁩، لا الملف.
3. بالنسبة إلى ⁨ECDSA⁩، أكّد أن التوقيع المُضمَّن مُرمَّز بـ ⁨DER⁩ — فالمُوقِّع يحوّل لك توقيع زوج الأعداد الصحيحة الخام.
4. افتح ملف ⁨PDF⁩ الموقَّع في مُتحقِّق مُعَدّ بمراسي ثقتك وأكّد أن التوقيع يُبلَّغ عنه باعتباره سليمًا تشفيريًا. التوقيع المُنتَج ليس توقيعًا مُتحقَّقًا منه؛ فقرار الثقة يخصّ المُتحقِّق.
5. أكّد عدم ظهور أي رمز أو اعتماد أو مادة مفاتيح في سجلّات تطبيقك.

الأمان والامتثال

• يبقى المفتاح في المزوِّد. استراتيجية ⁨KMS⁩ السحابية نقطة تكامل، لا مخزن مفاتيح. لا يحتفظ ⁨NextPDF Pro⁩ بالمفتاح الخاص لاستراتيجية ⁨KMS.⁩
• يعبر الملخّص الحدّ وحده. ترسل الجلسة ملخّص السمات الموقَّعة إلى المزوِّد، لا المستند — وهو نمط إدخال ملخّص الرسالة الموصوف في الإطار المرجعي لـ ⁨EU DSS.⁩
• يحسب المحرّك مدى البايتات. ولا يُقبَل من المُستدعِي مطلقًا.
• يفشل بإغلاق آمن. يثير إخفاق مزوِّد أو شبكة أو إصدار مفتاح أو خوارزمية غير مدعومة استثناءً مُصنَّفًا. ولا تنتج الجلسة بصمت مستندًا غير موقَّع، ولا تستبدل خوارزمية أضعف مطلقًا.
• الاعتمادات أسرار. الرموز واعتمادات مدير الخدمة تأتي من مدير أسرارك وتُستبعَد من السجلّات.

تتعلّق هذه الصفحة بالتوقيع التشفيري. كل مصدر معياري مُعاد صياغته؛ ولا يُعاد إنتاج أي نص معياري. ### حدّ عهدة المفاتيح

تعتمد حماية المفتاح على معالجة المفاتيح، و⁨KMS⁩ المُعَدّ، والنشر. يوفّر ⁨NextPDF Pro⁩ تكامل ⁨KMS⁩، لا مخزن المفاتيح. ‏⁨NextPDF Pro⁩ متوافق مع ⁨FIPS⁩ فقط حين يُعَدّ مقابل ⁨KMS⁩ أو ⁨HSM⁩ مُتحقَّق منه وفق ⁨FIPS؛⁩ وهو ليس بذاته وحدة تشفير مُتحقَّقًا منها وفق ⁨FIPS⁩ ولا يدّعي أي شهادة ⁨FIPS.⁩

معالجة الإخفاق

• إصدار مفتاح مجهول أو مُعطَّل. يربط المزوِّد استجابة غير موجود أو إصدار مُعطَّل باستثناء إدارة مفاتيح يسمّي المزوِّد والمفتاح.
• ⁨GCP⁩ من دون إصدار مثبَّت. يثير مُوقِّع ⁨GCP⁩ خطأ إدارة مفاتيح حين لا يزوّد الإعداد ولا الاستدعاء إصدارًا، لأن نقطة نهاية التوقيع غير المتماثل تعمل على إصدار محدَّد فقط.
• خوارزمية غير مدعومة. طلب خوارزمية لا يدعمها المزوِّد يثير استثناء خوارزمية غير مدعومة قبل أي استدعاء شبكي.
• إخفاق النقل. يُربَط خطأ عميل ⁨PSR-18⁩ باستثناء إخفاق توقيع؛ ولا تنتج الجلسة نتيجة جزئية.
• اعتماد مفقود. يثير المُوقِّع الذي لا يملك رمزًا ولا اعتمادات مدير خدمة خطأً مُصنَّفًا بدلًا من استدعاء المزوِّد بلا مصادقة.

انظر أيضًا

• الأمان — ⁨NextPDF Pro⁩ — الحجب، واكتشاف البيانات الشخصية، وكامل سطح التوقيع في ⁨Pro.⁩
• التوقيع عبر ⁨HSM⁩ — ⁨NextPDF Enterprise⁩ — عهدة المفاتيح العتادية عبر ⁨PKCS#11.⁩
• التوقيع — ⁨NextPDF Enterprise⁩ — مُنتِج ⁨PAdES B-LT⁩ و⁨B-LTA⁩ طويل الأمد.
• الأمان / التوقيع (⁨Core⁩) — مُوقِّع ⁨CMS⁩ في ⁨Core⁩ وعقد استراتيجية التوقيع.
• ⁨KMS⁩ · ⁨CMS⁩ · ⁨ECDSA⁩ · ⁨HSM⁩ — مصطلحات المسرد.