عقد مزود KMS

لمحة سريعة

HsmSignerInterface هو العقد العام الذي ينفّذه طرف ثالث لتوفير عهدة المفاتيح لـ ⁨NextPDF.⁩ يحتفظ مزودك بالمفتاح الخاص ضمن عهدته. ويبني المحرك بنية صياغة الرسائل المعمّاة (⁨CMS⁩).

التثبيت

composer require nextpdf/core:^3

نظرة عامة مفاهيمية

يفصل ⁨NextPDF⁩ تجميع التوقيع عن عهدة المفاتيح. يجهّز المحرك نطاق البايتات ويجمّع بنية ⁨CMS⁩ SignedData. ولا يحتفظ بالمفتاح الخاص، بل يفوّض عهدة المفاتيح إلى واجهة خلفية للتوقيع عبر عقد عام.

تنفّذ أحد ثلاثة عقود عمومية:

• SignerInterface. العقد الأساسي. يعيد SignatureResult للبيانات المزوّدة، ويطبّق طابعًا زمنيًا، ويبلّغ عن دعم التحقق طويل الأمد. استخدم هذا العقد عندما يعمل منطق التوقيع داخل العملية.
• HsmSignerInterface. عقد عهدة المفاتيح. يجب أن ينفّذ التطبيق التوقيع داخل الحد الجهازي. ويجب ألّا يغادر المفتاح الخاص ذلك الحد. ينفّذ مزود نظام إدارة المفاتيح هذا العقد.
• DeferredSignerInterface. امتداد لـ SignerInterface للواجهات الخلفية غير المتزامنة. يرسل المستدعي البيانات، ويتلقى معرّف مهمة، ثم يسترجع النتيجة لاحقًا.

تحدّد هذه الصفحة العقد العام. ولا تصف أي تطبيق داخلي لـ ⁨NextPDF Pro⁩ أو ⁨NextPDF Enterprise.⁩ قد يوفّر إصدار مدفوع تطبيقًا مدعومًا لهذا العقد. اعتمد على العقد، لا على التطبيق.

متطلب عهدة المفاتيح

يقتضي العقد ألّا يغادر المفتاح الخاص الحد الآمن أبدًا. وتدعم الممارسات الراسخة في إدارة المفاتيح هذا المتطلب. يتعامل المعهد الوطني للمعايير والتقنية (⁨NIST⁩) في ⁨SP 800-57 Part 1 Revision 5⁩ مع إدارة المفاتيح بوصفها إدارة لدورة الحياة تشمل التوليد والتخزين والتوزيع والاستخدام والإتلاف الآمن. ويجعل معيار تعمية المفتاح العمومي #11 (⁨PKCS⁩#11) ⁨v3.1⁩ هذا الحد قابلًا للإنفاذ. فعندما يضبط كائنُ مفتاحٍ خاص CKA_SENSITIVE إلى ⁨true⁩ أو CKA_EXTRACTABLE إلى ⁨false⁩، يجب ألّا يكشف الرمز قيمة المفتاح بنص صريح خارج الرمز.

تطبيقك مسؤول عن الالتزام بهذا المتطلب. لا يستطيع المحرك إنفاذه نيابةً عنك. إذا استطاعت طريقة sign() قراءة بايتات المفتاح الخام إلى ذاكرة العملية، فإن العقد يفقد خاصيته الأمنية.

سطح واجهة برمجة التطبيقات

NextPDF\Contracts\HsmSignerInterface (مستقر، منذ 1.0.0):

الطريقة	تعيد	الغرض
sign(string $data, string $algorithm)	string	وقّع البيانات داخل الحد الجهازي. أعد بايتات التوقيع الخام. ارمِ RuntimeException عند الفشل.
getCertificateDer()	string	أعد شهادة الموقّع ⁨X.509⁩ بصيغة قواعد التعمية المميّزة (⁨DER⁩).
getCertificateChainDer()	array<string>	أعد الشهادات الوسيطة، من المُصدِر إلى الجذر، باستثناء شهادة الموقّع.
getPublicKeyAlgorithm()	string	أعد معرّف خوارزمية المفتاح العمومي.

NextPDF\Contracts\SignerInterface (مستقر، منذ 1.0.0):

الطريقة	تعيد	الغرض
sign(string $data)	SignatureResult	أعد ⁨CMS⁩ SignedData المُرمَّز بـ ⁨DER.⁩
timestamp(string $signatureValue)	string	أعد رمز طابع زمني مُرمَّزًا بـ ⁨DER⁩ وفق طلب التعليقات (⁨RFC⁩) 3161.
supportsLtv()	bool	بلّغ عمّا إذا كان يمكن تضمين بيانات التحقق طويل الأمد (⁨LTV⁩).

NextPDF\Contracts\DeferredSignerInterface (تجريبي، منذ 3.0.0) يمدّ SignerInterface بـ submitForSigning() وretrieveSignature() وisComplete() للواجهات الخلفية غير المتزامنة.

تتبع مستويات التوقيع التي ينتجها المحرك ملفات تعريف التوقيعات الإلكترونية المتقدمة لـ ⁨PDF⁩ (⁨PAdES⁩). يحدّد المعهد الأوروبي لمعايير الاتصالات (⁨ETSI⁩) في ⁨EN 319 142-2⁩ ملفات تعريف ⁨PAdES⁩ الموسّعة التي تبنى على لبنات الأساس في ⁨EN 319 142-1.⁩ ويربط المحرك المستويات ⁨B-B⁩ و⁨B-T⁩ و⁨B-LT⁩ و⁨B-LTA⁩ بتلك اللبنات. يوفّر موقّعك العملية التعموية والمادة الشهادية التي يحتاجها المحرك.

نموذج التعليمات البرمجية — بداية سريعة

يفوّض هذا المزود البسيط، بأسلوب ⁨PKCS⁩#11، التوقيعَ إلى الرمز. ولا تقرأ ⁨PHP⁩ قيمة المفتاح أبدًا.

<?php

declare(strict_types=1);

use NextPDF\Contracts\HsmSignerInterface;

final class TokenSigner implements HsmSignerInterface
{
    public function __construct(private readonly TokenSession $session) {}

    public function sign(string $data, string $algorithm = 'sha256WithRSAEncryption'): string
    {
        // The token computes the signature. The key stays inside the token.
        return $this->session->c_sign($data, $algorithm);
    }

    public function getCertificateDer(): string
    {
        return $this->session->readCertificate();
    }

    /** @return array<string> */
    public function getCertificateChainDer(): array
    {
        return $this->session->readChain();
    }

    public function getPublicKeyAlgorithm(): string
    {
        return 'rsaEncryption';
    }
}

نموذج التعليمات البرمجية — للإنتاج

يتحقق مزود الإنتاج من المدخلات، ويفشل بأمان عند حدوث خطأ في الرمز، ولا يسجّل مادة المفاتيح أو التوقيع أبدًا.

<?php

declare(strict_types=1);

use NextPDF\Contracts\HsmSignerInterface;
use Psr\Log\LoggerInterface;
use RuntimeException;

final class KmsSigner implements HsmSignerInterface
{
    public function __construct(
        private readonly RemoteKmsClient $kms,
        private readonly string $keyId,
        private readonly LoggerInterface $logger,
    ) {}

    public function sign(string $data, string $algorithm = 'sha256WithRSAEncryption'): string
    {
        if ($data === '') {
            throw new RuntimeException('Refusing to sign empty data');
        }

        try {
            // The KMS performs the operation. The key never reaches this process.
            return $this->kms->sign($this->keyId, $data, $algorithm);
        } catch (\Throwable $error) {
            // Fail closed. Do not log key material or signature bytes.
            $this->logger->error('kms.sign.failed', ['key' => $this->keyId]);

            throw new RuntimeException('KMS signing failed', previous: $error);
        }
    }

    public function getCertificateDer(): string
    {
        return $this->kms->certificate($this->keyId);
    }

    /** @return array<string> */
    public function getCertificateChainDer(): array
    {
        return $this->kms->chain($this->keyId);
    }

    public function getPublicKeyAlgorithm(): string
    {
        return $this->kms->algorithm($this->keyId);
    }
}

الحالات الحدّية والمزالق

• تنسيق بايتات التوقيع. أعد بايتات التوقيع الخام. بالنسبة إلى ⁨Rivest-Shamir-Adleman⁩ (⁨RSA⁩)، تكون البايتات بصيغة ⁨DER.⁩ وبالنسبة إلى خوارزمية التوقيع الرقمي بالمنحنى الإهليلجي (⁨ECDSA⁩)، تكون البايتات قيمة r الخام متبوعةً بقيمة s.
• ترتيب السلسلة. يستثني getCertificateChainDer() شهادة الموقّع. رتّب الشهادات الوسيطة من المُصدِر إلى الجذر.
• معرّفات الخوارزميات. يستخدم sign() معرّفات بأسلوب ⁨OpenSSL.⁩ getPublicKeyAlgorithm() يعيد اسم خوارزمية ⁨X.509.⁩
• الفشل يفشل بأمان. ارمِ RuntimeException عند أي خطأ في الرمز أو ⁨KMS.⁩ لا تعد توقيعًا جزئيًا أو فارغًا.
• إتلاف المفاتيح. عندما يبلغ المفتاح نهاية فترة استخدامه التعموية، أتلفه وفقًا لإجراء إدارة المفاتيح لديك. ينص ⁨NIST SP 800-57 Part 1 Revision 5⁩ §8.2.1.2 على وجوب إتلاف المفتاح بمجرد أن تنتفي الحاجة إليه. ويتبع الإتلاف نفسه §8.3.4.

إقامة البيانات وإجراءات تخفيف مخاطر المعلومات الشخصية

ينقل العقد البيانات المراد توقيعها والمادة الشهادية فقط. ولا ينقل محتوى المستند أو البيانات الشخصية إلى الواجهة الخلفية للتوقيع. أبقِ نطاق البايتات في حده الأدنى. لا تضع بيانات شخصية في حقلي سبب التوقيع أو موقعه. فهذان الحقلان يظلان قابلين للملاحظة في الملف الموقّع.

القياس عن بُعد الآمن وتنظيف السجلات

لا تسجّل أبدًا البيانات المُمرَّرة إلى sign()، ولا بايتات التوقيع المُعادة، ولا معرّف المفتاح بصورة قابلة للاسترجاع، ولا أي مكوّن خاص للشهادة. سجّل نتيجة العملية ومرجعًا غير قابل للعكس فقط. خطّاف SignatureAppliedEvent هو مرتكز التدقيق المدعوم. راجع مشغّلات الإجراءات.

نموذج التهديد

الأصل	التهديد	إجراء التخفيف
المفتاح الخاص	التسرّب إلى ذاكرة العملية	يقتضي العقد التوقيع داخل الحد؛ ⁨PKCS⁩#11 CKA_SENSITIVE / CKA_EXTRACTABLE يفرضان عدم قابلية الاستخراج
أوراكل التوقيع	طلبات توقيع غير محدودة	يحدّ التطبيق من المعدل ويصادق على المستدعين
سلسلة الشهادات	الاستبدال	يعيد التطبيق سلسلة تبنى وصولًا إلى جذر موثوق
بايتات التوقيع	الإفصاح عبر السجلات	مسار خطأ يفشل بأمان؛ لا مادة توقيع في القياس عن بُعد
مفتاح تجاوز فترة استخدامه التعموية	الاستمرار في الاستخدام	إتلاف المفتاح وفق ⁨NIST SP 800-57 Part 1 Revision 5⁩ §8.2.1.2

المطابقة

تطابق مستويات التوقيع ملفات تعريف ⁨PAdES.⁩ يحدّد ⁨ETSI EN 319 142-2⁩ §5.1 ملفات تعريف ⁨PAdES⁩ الموسّعة المبنية على لبنات الأساس في ⁨EN 319 142-1.⁩ يجمّع المحرك تلك اللبنات من المادة التي يوفّرها موقّعك. تتوافق إدارة المفاتيح مع دورة حياة ⁨NIST SP 800-57 Part 1 Revision 5⁩، بما في ذلك متطلب الإتلاف في §8.2.1.2. وتتوافق عهدة المفاتيح الجهازية مع سمات المفاتيح غير القابلة للاستخراج في ⁨PKCS⁩#11 ⁨v3.1.⁩ الاستشهادات مسجّلة في المقدمة الأولية للصفحة.

ضبط التصدير وحوكمة المراجعة

تتناول هذه الصفحة عهدة المفاتيح في ⁨PKCS⁩#11 ووحدة الأمان الجهازية (⁨HSM⁩)، لذلك تضبط مقدمتها الأولية export_control_class: legal-review-required. بموجب سياسة مراجعة الوثائق (الخطة §17 البوابة 6)، تتطلب أي صفحة فيها وضع أمني أو مسار أو محتوى يطابق PAdES أو FIPS أو HSM أو PKCS#11 موافقةَ فريق @nextpdf-labs/crypto-reviewers على ⁨GitHub⁩ قبل أن تُنشَر. موافقة ⁨CODEOWNERS⁩ تلك بوابة دمج صارمة: تظل الصفحة publish: false حتى تكتمل كل من المراجعة القانونية لضبط التصدير ومراجعة @nextpdf-labs/crypto-reviewers.

السياق التجاري

يوفّر ⁨NextPDF Enterprise⁩ تطبيقًا مدعومًا لهذا العقد مع عهدة نظام إدارة المفاتيح وتجميع سلسلة الشهادات وتكامل التدقيق. يمكنك تنفيذ HsmSignerInterface بنفسك في ⁨Core⁩ أو استهلاك تطبيق ⁨Enterprise⁩ عبر العقد العام نفسه دون تغييرات في التعليمات البرمجية.

انظر أيضًا

• نظرة عامة على تأليف الامتدادات
• قواعد استقرار ⁨SPI⁩
• مشغّلات الإجراءات ومستمعو الأحداث

العقود والوحدات ذات الصلة

• مرجع عقود التوقيع — SignerInterface وHsmSignerInterface وDeferredSignerInterface ومزود الطابع الزمني.
• مرجع عقد سياسة الأمان — سطح واجهة مزود الخدمة (⁨SPI⁩) الشقيق الحساس أمنيًا.
• قواعد استقرار ⁨SPI⁩ — وعد الواجهة خلف عقود التوقيع stable.
• مشغّلات الإجراءات ومستمعو الأحداث — SignatureAppliedEvent، مرتكز التدقيق المدعوم.
• نظرة عامة على تأليف الامتدادات — سطح ⁨SPI⁩ العمومي الكامل.

يعرّف المسرد نظام إدارة المفاتيح وفترة الاستخدام التعموية و⁨HSM⁩؛ راجع المسرد المنشور للحصول على كل تعريف معياري.