واجهة PKI (PKI API)
واجهة الإدارة المصادَق عليها لـ PKI في Cockpit — سلطات الشهادات، والشهادات، والمُصدرون، والإبطال، والنشر، والاكتشاف، والامتثال — إضافة إلى نقاط نهاية البروتوكول العامة التي يستدعيها العملاء القياسيون للتسجيل والتحقق من حالة الشهادة.
تضم واجهة PKI API عائلتَي نقاط نهاية. واجهة الإدارة (/api/pki/…) تتم المصادقة عليها بجلسة مستخدم Cockpit، وتكون محددة النطاق بمستأجرك، وتخضع لبوابة أذونات Operations.Pki.*؛ وهي تُنشئ سلطات الشهادات والشهادات والمُصدرين وأهداف النشر والماسحات وتُشغّلها. أما نقاط نهاية البروتوكول العامة (تنزيل ACME وEST وSCEP وCMP وOCSP وCRL) فتُقدَّم على مساراتها القياسية الخاصة بها، ويستدعيها مباشرة عملاء ACME/EST/SCEP/CMP ومستجيبات OCSP والأطراف المعتمِدة — وتُصادِق بآلياتها البروتوكولية الخاصة، لا برمز Cockpit.
| العائلة | المسار الأساسي | المصادقة | الغرض |
|---|---|---|---|
| واجهة الإدارة (Management API) | /api/pki/… | جلسة مستخدم Cockpit (JWT)، أذونات Operations.Pki.* | إنشاء وتشغيل سلطات الشهادات والشهادات والمُصدرين والنشر والاكتشاف |
| نقاط نهاية البروتوكول العامة | مسارات جذرية مثل /ocsp/…، /scep/…، /cmp/…، .well-known/est/…، ودليل ACME | معيار كل بروتوكول على حدة (مفاتيح حساب ACME، ونقل EST/SCEP/CMP، وHTTP عادي لـ OCSP/CRL) | بروتوكولات التسجيل وحالة الشهادة التي يتحدث بها العملاء مباشرة |
الصفوف التي يحمل الغرض منها العلامة (public) يمكن الوصول إليها دون جلسة Cockpit — فهي أسطح البروتوكول القياسية. أما باقي الصفوف فهي مسارات إدارة وتتطلب إذن Operations.Pki.* المناظر.
سلطات الشهادات
سلطات شهادات جذرية ووسيطة وخارجية، بدورة حياة كاملة وخاضعة للتدقيق — التعليق، وإعادة التفعيل، والإبطال (بسيط أو تسلسلي)، والأرشفة — إضافة إلى السلسلة، ومعاينة الأثر، وCRL. تُطابِق الإجراءات أذونات Operations.Pki.CAs.*.
| الطريقة + المسار | الغرض |
|---|---|
GET · POST /api/pki/cas | سرد سلطات الشهادات · إنشاء سلطة شهادات جذرية |
GET · PUT /api/pki/cas/{id} | الحصول على سلطة شهادات · تحديثها |
POST /api/pki/cas/{id}/intermediate | إنشاء سلطة شهادات وسيطة |
GET /api/pki/cas/{id}/chain | الحصول على سلسلة شهادات سلطة الشهادات |
GET /api/pki/cas/{id}/lifecycle/impact | معاينة نطاق تأثير دورة الحياة |
POST /api/pki/cas/{id}/lifecycle/suspend · /reactivate | تعليق · إعادة تفعيل |
POST /api/pki/cas/{id}/revoke | إبطال (بسيط) |
POST /api/pki/cas/{id}/lifecycle/revoke | إبطال تسلسلي (سلطة الشهادات + السلطات الفرعية + الشهادات الصادرة) |
POST /api/pki/cas/{id}/lifecycle/archive · /unarchive | أرشفة · إلغاء الأرشفة |
GET · POST /api/pki/cas/{id}/crl | الحصول على CRL سلطة الشهادات · إنشاؤه |
استدعِ مسار lifecycle/impact أولاً — فهو يُعيد تقريراً للقراءة فقط يحدد بدقة السلطات الفرعية والشهادات التي سيؤثر فيها الإبطال التسلسلي.
الشهادات والطلبات
تُصدَر الشهادات مباشرة تحت سلطة شهادات، أو عبر سير عمل الطلبات (تقديم، ثم اعتماد / رفض). ويخضع كلا المسارين لأذونات إصدار شهادات PKI.
| الطريقة + المسار | الغرض |
|---|---|
POST /api/pki/cas/{id}/certificates | إصدار شهادة تحت سلطة شهادات |
/api/pki/requests | سير عمل طلب الشهادة — تقديم، ثم اعتماد / رفض |
الإصدار تحت سلطة شهادات يُطابِق POST /api/pki/cas/{id}/certificates؛ ويستخدم سير عمل الطلبات /api/pki/requests مع إجراءات الاعتماد / الرفض. راجع إنشاء شهادة.
المُصدرون
المُصدر (issuer) هو جهة تزويد مُهيَّأة (مثل حساب ACME أو سلطة شهادات خارجية) تستخدمها المنصة للحصول على الشهادات. يمكن اختبار المُصدرين وتفعيلهم/تعطيلهم واستخدامهم لتشغيل دورة حياة الشهادة.
| الطريقة + المسار | الغرض |
|---|---|
GET · POST /api/pki/issuers | سرد · إنشاء مُصدر |
GET · PUT · DELETE /api/pki/issuers/{id} | إدارة مُصدر |
POST /api/pki/issuers/{id}/test | اختبار الاتصال |
PUT /api/pki/issuers/{id}/status | تحديث الحالة |
POST /api/pki/issuers/{id}/register | تسجيل حساب ACME |
POST /api/pki/issuers/{id}/issue · /renew · /revoke | دورة حياة الشهادة عبر المُصدر |
بروتوكولات التسجيل
لكل بروتوكول سطح إدارة على واجهة الإدارة (التهيئة، والملفات التعريفية، والأسماء المستعارة، والحالة) وسطح بروتوكول عام على مسارات قياسية يتحدث بها العملاء مباشرة. الصفوف العامة مُعلَّمة بـ (public).
ACME (RFC 8555)
خادم ACME كامل لكل سلطة شهادات: directory، وnew-nonce، وnew-account، وnew-order، وauthorization، وchallenge، وfinalize، وتنزيل الشهادة، وrevoke-cert. وجّه أي عميل ACME (أو مُصدر ACME الخاص بـ cert-manager) إلى عنوان URL لدليل ACME الخاص بسلطة الشهادات.
| الطريقة + المسار | الغرض |
|---|---|
GET /api/pki/acme/{ca_id}/config | تهيئة إدارة ACME |
…/acme/{ca_id}/directory | دليل ACME (public) |
…/new-nonce · /new-acct · /new-order | سير عمل الحساب والطلب (public) |
…/authz/{id} · /challenge/{id} · /order/{id}/finalize | التفويض، والتحدي، والإنهاء (public) |
…/cert/{id} · /revoke-cert | التنزيل والإبطال (public) |
EST (RFC 7030)
التسجيل عبر النقل الآمن (Enrollment over Secure Transport): cacerts، وsimpleenroll، وsimplereenroll، وserverkeygen، وcsrattrs، مقدَّمة تحت المسار القياسي .well-known/est/.
| الطريقة + المسار | الغرض |
|---|---|
GET /api/pki/est/{ca_id}/cacerts | شهادات سلطة الشهادات |
.well-known/est/{slug}/* | simpleenroll / simplereenroll / serverkeygen / csrattrs (public) |
GET · PUT /api/pki/est/{ca_id}/config · /enrollments | إدارة EST |
SCEP (RFC 8894)
بروتوكول Simple Certificate Enrollment Protocol (SCEP) مع ملفات تعريفية (profiles) قابلة للتهيئة. تخدم نقطة النهاية العامة pkiclient.exe طلبات GET/POST لعملاء SCEP الكلاسيكيين.
| الطريقة + المسار | الغرض |
|---|---|
GET · POST /api/pki/scep/profiles · /profiles/{id} | إدارة الملفات التعريفية لـ SCEP |
…/{profile_id}/status | حالة التسجيل |
GET · POST /scep/{slug}/pkiclient.exe | بروتوكول SCEP (public) |
CMP (RFC 4210 / 9483)
بروتوكول Certificate Management Protocol (CMP) مع أسماء مستعارة (aliases) مسمّاة، وتتبّع للمعاملات، ومقاييس لكل اسم مستعار. يرسل العملاء طلبات POST إلى نقطة نهاية رسائل CMP.
| الطريقة + المسار | الغرض |
|---|---|
GET · POST /api/pki/cmp/aliases · /aliases/{id} | إدارة الأسماء المستعارة لـ CMP |
…/aliases/{id}/transactions · /transactions/{id} | سجل المعاملات |
POST /cmp/{alias} | بروتوكول CMP (public) |
Kubernetes cert-manager
سجّل DuoKey كـ مُصدر خارجي (external issuer) لـ cert-manager: يرسل cert-manager طلبات CSR إلى نقطة نهاية التوقيع، وتُعيد DuoKey شهادات موقَّعة، مما يبقي المفاتيح التي تديرها Kubernetes مسجَّلة مقابل سلطة الشهادات الخاصة بك.
| الطريقة + المسار | الغرض |
|---|---|
POST · GET /api/pki/certmanager/issuers | تسجيل / سرد المُصدرين الخارجيين |
…/issuers/{id}/status | حالة المُصدر |
/api/pki/certmanager/sign | توقيع طلب CSR من cert-manager |
/api/pki/certmanager/healthz | فحص السلامة |
خادم KMIP 2.1
يمكن لـ DuoKey أن يعمل كـ خادم KMIP، ويعرض كائنات وعمليات المفاتيح / الشهادات لعملاء KMIP.
| الطريقة + المسار | الغرض |
|---|---|
GET · POST /api/pki/kmip-server/{endpoint_id}/objects | كائنات KMIP |
…/operations · /stats · /test | العمليات، والإحصاءات، واختبار الاتصال |
دورة حياة نقطة النهاية الموحدة
تشترك جميع نقاط نهاية البروتوكولات (EST / SCEP / ACME / CMP / KMIP) في دورة حياة نقطة نهاية موحّدة — النشر، والبدء، والإيقاف المؤقت، والإيقاف — مع السلامة والمقاييس، بحيث يمكنك تشغيلها بشكل متسق.
| الطريقة + المسار | الغرض |
|---|---|
GET · POST /api/endpoints · /endpoints/{id} | إدارة نقاط نهاية البروتوكولات |
…/{id}/start · /pause · /stop | التحكم بدورة الحياة |
…/{id}/health · /metrics | السلامة والمقاييس |
الإبطال (CRL وOCSP)
تُبطَل الشهادات وسلطات الشهادات بسبب قياسي وفق RFC 5280. ويؤثر الإبطال فوراً في قناتي النشر كلتيهما: CRL الخاصة بسلطة الشهادات، ومستجيب OCSP التابع لها.
CRL — قوائم إبطال الشهادات
تُصدر كل سلطة شهادات قائمة CRL موقَّعة بصيغة DER، تُنشر على عنوان URL لتوزيع CRL المحمول في الشهادات الصادرة. يمكن إنشاء قوائم CRL عند الطلب أو بالإجبار، وفحصها عبر معلومات CRL. تنزيل DER عام.
| الطريقة + المسار | الغرض |
|---|---|
GET /api/pki/crls | سرد قوائم CRL |
GET /api/pki/crl/{ca_id}/info | بيانات CRL الوصفية (الرقم، والتحديث الحالي/التالي) |
POST /api/pki/crl/{ca_id}/generate | فرض إنشاء CRL |
GET /api/pki/crl/{ca_id} | تنزيل CRL بصيغة DER (public) |
GET · POST /api/pki/cas/{id}/crl | الحصول على CRL سلطة الشهادات · إنشاؤه |
OCSP — بروتوكول حالة الشهادة عبر الإنترنت
للحصول على الحالة في الوقت الفعلي دون تنزيل قائمة كاملة، يمكن لكل سلطة شهادات تشغيل مستجيب OCSP. وللمستجيبات دورة حياة خاصة بها (النشر، والبدء، والإيقاف المؤقت، والإيقاف) إضافة إلى السلامة والمقاييس، وتستخدم شهادة توقيع OCSP مخصصة. بروتوكول المستجيب وفحص سلامته عامّان.
| الطريقة + المسار | الغرض |
|---|---|
POST · GET /ocsp/{slug} | بروتوكول مستجيب OCSP (public) |
GET /ocsp/{slug}/health | سلامة المستجيب (public) |
GET · POST /api/ocsp/responders · /responders/{id} | إدارة المستجيبين |
…/responders/{id}/start · /pause · /stop | دورة حياة المستجيب |
…/responders/{id}/health · /metrics | السلامة والمقاييس |
النشر
دفع الشهادات الصادرة إلى أهداف حية — أجهزة F5 وFortinet، وأهداف Windows تُدار عبر عميل (Microsoft IIS، وActive Directory / LDAPS، وWindows CAPI)، وأهداف يمكن الوصول إليها عبر SSH (Nginx وJava Keystore)، وأهداف ويب/تطبيقات عامة أخرى (Azure App Service وEntra ID وApache HTTPD) — مع مهام نشر، وتراجع (rollback)، وملفات تعريفية للاتصال قابلة لإعادة الاستخدام، ومزامنة CMDB مع ServiceNow.
| الطريقة + المسار | الغرض |
|---|---|
GET · POST · PATCH · DELETE /api/pki/deploy/f5/targets | إدارة أهداف F5 |
POST /api/pki/deploy/f5/deploy · /f5/deploy-cert-only | النشر إلى F5 |
GET · POST · PATCH · DELETE /api/pki/deploy/fortinet/targets | إدارة أهداف Fortinet |
POST /api/pki/deploy/fortinet/deploy · /fortinet/jobs/{id}/rollback | النشر إلى Fortinet · التراجع عنه |
GET · POST · PATCH · DELETE /api/pki/deploy/windows/targets · /targets/{id} | إدارة الأهداف التي تُدار عبر عميل (windows_iis، وactive_directory_ldaps، وcapi) |
POST /api/pki/deploy/windows/deploy | وضع مهمة نشر في قائمة الانتظار ليجلبها العميل المرتبط وينفّذها |
POST /api/pki/deploy/windows/jobs/{id}/rollback | وضع مهمة تراجع في قائمة الانتظار |
GET /api/pki/orchestrator/jobs · POST /jobs/{id}/report | جلب المهام من قبل العميل والإبلاغ عن النتيجة — مصادقة بمفتاح العميل، وليست مساراً لجلسة Cockpit |
GET · POST · PUT · DELETE /api/pki/deploy/targets | الأهداف العامة (Azure App Service، وEntra ID، وApache HTTPD، وNginx، وJava Keystore) |
POST /api/pki/deploy/targets/{id}/deploy-entra · /deploy-app-service · /deploy-ssh | النشر إلى Entra ID · Azure App Service · هدف SSH (Nginx / Java Keystore) |
POST /api/pki/deploy/targets/{id}/test | التحقق من اتصال/بيانات اعتماد هدف قبل النشر |
GET /api/pki/deploy/jobs · /jobs/{id} | سرد / الحصول على مهام النشر |
POST /api/pki/deploy/jobs/{id}/rollback | التراجع عن مهمة نشر |
GET · POST · PUT · DELETE /api/pki/connections · /connections/{id} | ملفات تعريفية لاتصال بيانات الاعتماد قابلة لإعادة الاستخدام |
/api/pki/connectors/servicenow/* | مزامنة جرد CMDB / انتهاء الصلاحية مع ServiceNow |
الاكتشاف والامتثال
اعثر على الشهادات عبر الشبكة باستخدام الماسحات والعملاء (agents) المثبَّتين، واستورد الشهادات المكتشَفة إلى المخزون، وشغّل تدقيقات SSL/TLS وتقييم الامتثال لكل شهادة مقابل الأطر أو سياسات مستأجرك الخاصة.
| الطريقة + المسار | الغرض |
|---|---|
GET · POST /api/pki/scanners · /scanners/{id} | إدارة الماسحات (فحص / تفعيل / تعطيل / مهام) |
GET /api/pki/scanners/certificates · /certificates/{id} | تصفّح الشهادات المكتشَفة |
POST /api/pki/scanners/certificates/{id}/import | استيراد شهادة مكتشَفة |
GET · POST /api/pki/scanners/agents · /agents/register | أسطول عملاء الماسح |
…/agents/{id}/rotate-key · /revoke | تدوير / إبطال مفتاح العميل |
GET · POST /api/pki/scanner/targets · /results · /summary | أهداف الفحص، والنتائج، والملخص |
GET · POST /api/pki/scanner/certs/{id}/ssl-audit | تشغيل / عرض تدقيق SSL لشهادة |
…/ssl-audit/history · /run · /compliance | سجل التدقيق، والتشغيل، ونتيجة الامتثال |
GET · POST /api/pki/scanner/ssl-compliance/frameworks | أطر الامتثال |
/api/pki/scanner/compliance/* | سياسات امتثال المستأجر وتقييمها |