chrome.certificateProvider

الوصف

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

الأذونات

certificateProvider

مدى التوفّر

الإصدار 46 من Chrome والإصدارات الأحدث نظام التشغيل ChromeOS فقط

المفاهيم والاستخدام

يتم عادةً استخدام واجهة برمجة التطبيقات هذه لعرض شهادات العميل على ChromeOS باتّباع الخطوات التالية:

  • تسجّل الإضافة في الحدثَين onCertificatesUpdateRequested وonSignatureRequested.
  • تتصل الإضافة setCertificates() لتقديم القائمة الأولية للشهادات بعد عملية التهيئة.
  • تراقب الإضافة التغييرات في قائمة الشهادات المتاحة وتطلب setCertificates() لإعلام المتصفح بكل تغيير من هذا النوع.
  • أثناء عملية المصافحة عبر بروتوكول TLS، يتلقّى المتصفّح طلب شهادة عميل. باستخدام حدث onCertificatesUpdateRequested، يطلب المتصفّح من الإضافة إعداد تقرير عن جميع الشهادات التي توفّرها حاليًا.
  • ترسل الإضافة تقارير تتضمّن الشهادات المتاحة حاليًا باستخدام طريقة setCertificates().
  • يُطابق المتصفّح جميع الشهادات المتاحة مع طلب شهادة العميل من المضيف البعيد. يتم عرض النتائج المطابقة للمستخدم في مربّع حوار اختيار.
  • يمكن للمستخدم اختيار شهادة وبالتالي الموافقة على المصادقة أو إلغاؤها.
مربّع حوار اختيار الشهادة
مربّع حوار اختيار الشهادة
  • في حال ألغى المستخدم عملية المصادقة أو لم تتطابق أي شهادة مع الطلب، سيتم إلغاء مصادقة عميل بروتوكول أمان طبقة النقل (TLS).
  • بخلاف ذلك، إذا وافق المستخدم على المصادقة باستخدام شهادة تقدّمها هذه الإضافة، يطلب المتصفّح من الإضافة توقيع البيانات لمواصلة عملية تبادل بيانات بروتوكول أمان طبقة النقل (TLS). يتم إرسال الطلب كحدث onSignatureRequested.
  • يحتوي هذا الحدث على بيانات الإدخال، ويحدّد الخوارزمية التي يجب استخدامها لإنشاء التوقيع، ويشير إلى إحدى الشهادات التي أبلغت عنها هذه الإضافة. يجب أن تنشئ الإضافة توقيعًا للبيانات المحدّدة باستخدام المفتاح الخاص المرتبط بالشهادة المشار إليها. قد يتطلّب إنشاء التوقيع إضافة DigestInfo في البداية وتعبئة النتيجة قبل التوقيع الفعلي.
  • ترسل الإضافة التوقيع مرة أخرى إلى المتصفح باستخدام الطريقة reportSignature(). إذا تعذّر احتساب التوقيع، يجب استدعاء الطريقة بدون توقيع.
  • في حال تقديم التوقيع، يكمل المتصفّح عملية تأكيد الاتصال من خلال بروتوكول أمان طبقة النقل.

قد يختلف التسلسل الفعلي للخطوات. على سبيل المثال، لن يُطلب من المستخدم اختيار شهادة إذا تم استخدام سياسة المؤسسة لاختيار شهادة تلقائيًا (راجِع AutoSelectCertificateForUrls وسياسات Chrome للمستخدمين).

في الإضافة، يمكن أن يبدو ذلك مشابهًا للمقتطف التالي:

function collectAvailableCertificates() {   // Return all certificates that this Extension can currently provide.   // For example:   return [{     certificateChain: [new Uint8Array(...)],     supportedAlgorithms: ['RSASSA_PKCS1_v1_5_SHA256']   }]; }  // The Extension calls this function every time the currently available list of // certificates changes, and also once after the Extension's initialization. function onAvailableCertificatesChanged() {   chrome.certificateProvider.setCertificates({     clientCertificates: collectAvailableCertificates()   }); }  function handleCertificatesUpdateRequest(request) {   // Report the currently available certificates as a response to the request   // event. This is important for supporting the case when the Extension is   // unable to detect the changes proactively.   chrome.certificateProvider.setCertificates({     certificatesRequestId: request.certificatesRequestId,     clientCertificates: collectAvailableCertificates()   }); }  // Returns a private key handle for the given DER-encoded certificate. // |certificate| is an ArrayBuffer. function getPrivateKeyHandle(certificate) {...}  // Digests and signs |input| with the given private key. |input| is an // ArrayBuffer. |algorithm| is an Algorithm. // Returns the signature as ArrayBuffer. function signUnhashedData(privateKey, input, algorithm) {...}  function handleSignatureRequest(request) {   // Look up the handle to the private key of |request.certificate|.   const key = getPrivateKeyHandle(request.certificate);   if (!key) {     // Handle if the key isn't available.     console.error('Key for requested certificate no available.');      // Abort the request by reporting the error to the API.     chrome.certificateProvider.reportSignature({       signRequestId: request.signRequestId,       error: 'GENERAL_ERROR'     });     return;   }    const signature = signUnhashedData(key, request.input, request.algorithm);   chrome.certificateProvider.reportSignature({     signRequestId: request.signRequestId,     signature: signature   }); }  chrome.certificateProvider.onCertificatesUpdateRequested.addListener(     handleCertificatesUpdateRequest); chrome.certificateProvider.onSignatureRequested.addListener(     handleSignatureRequest);

الأنواع

Algorithm

الإصدار 86 من Chrome والإصدارات الأحدث

أنواع خوارزميات التوقيعات المشفرة المتوافقة

Enum

"RSASSA_PKCS1_v1_5_MD5_SHA1"
تحدّد خوارزمية توقيع RSASSA PKCS#1 v1.5 مع التجزئة MD5-SHA-1. يجب ألا تضيف الإضافة بادئة DigestInfo، بل يجب أن تضيف فقط مساحة متروكة وفقًا لمعيار PKCS#1. تم إيقاف هذه الخوارزمية نهائيًا ولن يطلبها Chrome بدءًا من الإصدار 109.

"RSASSA_PKCS1_v1_5_SHA1"
تحدّد خوارزمية توقيع RSASSA PKCS#1 v1.5 مع وظيفة التجزئة SHA-1.

"RSASSA_PKCS1_v1_5_SHA256"
تحدّد خوارزمية توقيع RSASSA PKCS#1 v1.5 مع دالة التجزئة SHA-256.

"RSASSA_PKCS1_v1_5_SHA384"
تحدّد خوارزمية توقيع RSASSA PKCS#1 v1.5 مع وظيفة التجزئة SHA-384.

"RSASSA_PKCS1_v1_5_SHA512"
تحدّد خوارزمية توقيع RSASSA PKCS#1 v1.5 مع وظيفة التجزئة SHA-512.

"RSASSA_PSS_SHA256"
تحدّد خوارزمية توقيع RSASSA PSS مع دالة التجزئة SHA-256 ودالة إنشاء القناع MGF1 والملح الذي له الحجم نفسه مثل التجزئة.

‫"RSASSA_PSS_SHA384"
تحدّد خوارزمية توقيع RSASSA PSS مع وظيفة التجزئة SHA-384 ووظيفة إنشاء القناع MGF1 والملح الذي له الحجم نفسه مثل التجزئة.

"RSASSA_PSS_SHA512"
تحدّد خوارزمية توقيع RSASSA PSS مع وظيفة التجزئة SHA-512 ووظيفة إنشاء القناع MGF1 والملح الذي له الحجم نفسه مثل التجزئة.

CertificateInfo

الخصائص

  • الشهادة

    ArrayBuffer

    يجب أن يكون ترميز DER لشهادة X.509. في الوقت الحالي، لا تتوفّر سوى شهادات مفاتيح RSA.

  • supportedHashes

    Hash[]

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

CertificatesUpdateRequest

الإصدار 86 من Chrome والإصدارات الأحدث

الخصائص

  • certificatesRequestId

    الرقم

    معرّف الطلب الذي سيتم تمريره إلى setCertificates

ClientCertificateInfo

الإصدار 86 من Chrome والإصدارات الأحدث

الخصائص

  • certificateChain

    ArrayBuffer[]

    يجب أن يحتوي الصفيف على ترميز DER لشهادة عميل X.509 كعنصر أول.

    يجب أن تتضمّن هذه السمة شهادة واحدة بالضبط.

  • supportedAlgorithms

    Algorithm[]

    جميع الخوارزميات المتوافقة مع هذه الشهادة لن يُطلب من الإضافة توقيع الطلبات إلا باستخدام إحدى هذه الخوارزميات.

Error

الإصدار 86 من Chrome والإصدارات الأحدث

أنواع الأخطاء التي يمكن للإضافة إبلاغك بها

القيمة

"GENERAL_ERROR"

Hash

تمّ الإيقاف. تم استبداله بـ Algorithm.

Enum

‫"MD5_SHA1"
تحدّد خوارزميات التجزئة MD5 وSHA1.

‫"SHA1"
تحدّد خوارزمية التجزئة SHA1.

"SHA256"
تحدّد خوارزمية التجزئة SHA256.

"SHA384"
تحدّد خوارزمية التجزئة SHA384.

"SHA512"
تحدّد خوارزمية التجزئة SHA512.

PinRequestErrorType

Chrome 57 والإصدارات الأحدث

أنواع الأخطاء التي يمكن عرضها للمستخدم من خلال الدالة requestPin.

Enum

‫"INVALID_PIN"
تحدّد هذه السمة أنّ رقم التعريف الشخصي غير صالح.

‫"INVALID_PUK"
تحدّد هذه السمة أنّ رمز PUK غير صالح.

‫"MAX_ATTEMPTS_EXCEEDED"
يشير إلى أنّه تم تجاوز الحد الأقصى لعدد المحاولات.

‫"UNKNOWN_ERROR"
تحدّد هذه السمة أنّه لا يمكن تمثيل الخطأ بالأنواع المذكورة أعلاه.

PinRequestType

Chrome 57 والإصدارات الأحدث

نوع الرمز المطلوب من خلال الإضافة باستخدام الدالة requestPin.

Enum

"PIN"
تحدّد هذه السمة أنّ الرمز المطلوب هو رقم تعريف شخصي.

"PUK"
تحدّد هذه السمة أنّ الرمز المطلوب هو رمز PUK.

PinResponseDetails

Chrome 57 والإصدارات الأحدث

الخصائص

  • userInput

    سلسلة اختيارية

    الرمز الذي يقدّمه المستخدم. تكون فارغة إذا أغلق المستخدم مربّع الحوار أو حدث خطأ آخر.

ReportSignatureDetails

الإصدار 86 من Chrome والإصدارات الأحدث

الخصائص

  • خطأ

    "GENERAL_ERROR"
     اختياري

    الخطأ الذي حدث أثناء إنشاء التوقيع، إن وُجد.

  • signRequestId

    الرقم

    معرّف الطلب الذي تمّ تلقّيه من خلال الحدث onSignatureRequested.

  • توقيع

    ArrayBuffer اختياري

    التوقيع، إذا تم إنشاؤه بنجاح

RequestPinDetails

Chrome 57 والإصدارات الأحدث

الخصائص

  • attemptsLeft

    number اختياري

    عدد المحاولات المتبقية يتم توفير ذلك حتى تتمكّن أي واجهة مستخدم من عرض هذه المعلومات للمستخدم. لا يُتوقّع أن يفرض Chrome ذلك، بل يجب أن تستدعي الإضافة stopPinRequest مع errorType = MAX_ATTEMPTS_EXCEEDED عند تجاوز عدد طلبات رقم التعريف الشخصي.

  • errorType

    PinRequestErrorType اختيارية

    نموذج الخطأ المعروض للمستخدم. يجب ضبط هذا الحقل في حال تعذّر تنفيذ الطلب السابق، وذلك لإبلاغ المستخدم بسبب التعذّر.

  • requestType

    ‫PinRequestType اختياري

    تمثّل هذه السمة نوع الرمز المطلوب. الإعداد التلقائي هو رقم التعريف الشخصي.

  • signRequestId

    الرقم

    المعرّف الذي يقدّمه Chrome في SignRequest

SetCertificatesDetails

الإصدار 86 من Chrome والإصدارات الأحدث

الخصائص

  • certificatesRequestId

    number اختياري

    عندما يتم استدعاؤها استجابةً للطلب onCertificatesUpdateRequested، يجب أن تحتوي على قيمة certificatesRequestId التي تم تلقّيها. وفي ما عدا ذلك، يجب إلغاء ضبطه.

  • clientCertificates

    ClientCertificateInfo[]

    قائمة بشهادات العميل المتوفّرة حاليًا

  • خطأ

    "GENERAL_ERROR"
     اختياري

    الخطأ الذي حدث أثناء استخراج الشهادات، إن وُجد. سيظهر هذا الخطأ للمستخدم عند الاقتضاء.

SignatureRequest

الإصدار 86 من Chrome والإصدارات الأحدث

الخصائص

  • خوارزمية

    الخوارزمية

    خوارزمية التوقيع التي سيتم استخدامها

  • الشهادة

    ArrayBuffer

    ترميز DER لشهادة X.509 يجب أن توقّع الإضافة input باستخدام المفتاح الخاص المرتبط بها.

  • input

    ArrayBuffer

    البيانات المطلوب توقيعها يُرجى العِلم أنّ البيانات غير مجزّأة.

  • signRequestId

    الرقم

    معرّف الطلب الذي سيتم تمريره إلى reportSignature

SignRequest

الخصائص

  • الشهادة

    ArrayBuffer

    ترميز DER لشهادة X.509 يجب أن توقّع الإضافة digest باستخدام المفتاح الخاص المرتبط بها.

  • سلسلة تمت تجزئتها

    ArrayBuffer

    الملخّص الذي يجب توقيعه

  • تجزئة

    التجزئة

    يشير إلى خوارزمية التجزئة التي تم استخدامها لإنشاء digest.

  • signRequestId

    الرقم

    Chrome 57 والإصدارات الأحدث

    المعرّف الفريد الذي ستستخدمه الإضافة إذا احتاجت إلى طلب طريقة تتطلّب ذلك، مثل requestPin.

StopPinRequestDetails

Chrome 57 والإصدارات الأحدث

الخصائص

  • errorType

    PinRequestErrorType اختيارية

    نموذج الخطأ إذا كان هذا الحقل متوفّرًا، سيتم عرضه للمستخدم. يُقصد به أن يتضمّن سبب إيقاف التدفق إذا كان ناتجًا عن خطأ، مثل MAX_ATTEMPTS_EXCEEDED.

  • signRequestId

    الرقم

    المعرّف الذي يقدّمه Chrome في SignRequest

الطُرق

reportSignature()

الإصدار 86 من Chrome والإصدارات الأحدث 
chrome.certificateProvider.reportSignature(
  details: ReportSignatureDetails,
): Promise<void>

يجب أن يتم استدعاء هذه الدالة استجابةً للحدث onSignatureRequested.

يجب أن تستدعي الإضافة هذه الدالة في النهاية لكل حدث onSignatureRequested. ستتوقف عملية تنفيذ واجهة برمجة التطبيقات عن انتظار هذا الاستدعاء بعد فترة من الوقت وستردّ برسالة خطأ انتهاء المهلة عند استدعاء هذه الدالة.

المعلمات

المرتجعات

  • Promise<void>

    الإصدار 96 من Chrome والإصدارات الأحدث

requestPin()

Chrome 57 والإصدارات الأحدث 
chrome.certificateProvider.requestPin(
  details: RequestPinDetails,
): Promise<PinResponseDetails | undefined>

يطلب هذا الإجراء من المستخدم إدخال رقم التعريف الشخصي. يُسمح بطلب واحد فقط في كل مرة. ويتم رفض الطلبات التي يتم إصدارها أثناء تنفيذ مسار آخر. وتتحمّل الإضافة مسؤولية إعادة المحاولة لاحقًا إذا كان هناك تدفق آخر قيد التنفيذ.

المعلمات

  • التفاصيل

    RequestPinDetails

    تحتوي على تفاصيل حول مربّع الحوار المطلوب.

المرتجعات

  • Promise<PinResponseDetails | undefined>

    الإصدار 96 من Chrome والإصدارات الأحدث

setCertificates()

الإصدار 86 من Chrome والإصدارات الأحدث 
chrome.certificateProvider.setCertificates(
  details: SetCertificatesDetails,
): Promise<void>

تحدّد هذه السياسة قائمة بالشهادات التي سيتم استخدامها في المتصفّح.

يجب أن تستدعي الإضافة هذه الدالة بعد عملية التهيئة وعند كل تغيير في مجموعة الشهادات المتاحة حاليًا. يجب أن تستدعي الإضافة أيضًا هذه الدالة استجابةً إلى onCertificatesUpdateRequested في كل مرة يتم فيها تلقّي هذا الحدث.

المعلمات

  • التفاصيل

    SetCertificatesDetails

    الشهادات المطلوب ضبطها وسيتم تجاهل الشهادات غير الصالحة.

المرتجعات

  • Promise<void>

    الإصدار 96 من Chrome والإصدارات الأحدث

stopPinRequest()

Chrome 57 والإصدارات الأحدث 
chrome.certificateProvider.stopPinRequest(
  details: StopPinRequestDetails,
): Promise<void>

توقف طلب رقم التعريف الشخصي الذي بدأته الدالة requestPin.

المعلمات

  • التفاصيل

    StopPinRequestDetails

    يحتوي على تفاصيل حول سبب إيقاف مسار الطلب.

المرتجعات

  • Promise<void>

    الإصدار 96 من Chrome والإصدارات الأحدث

الفعاليات

onCertificatesUpdateRequested

الإصدار 86 من Chrome والإصدارات الأحدث 
chrome.certificateProvider.onCertificatesUpdateRequested.addListener(
  callback: function,
)

يتم تنشيط هذا الحدث إذا كانت الشهادات التي تم ضبطها من خلال setCertificates غير كافية أو إذا طلب المتصفّح معلومات محدّثة. يجب أن تتصل الإضافة بالدالة setCertificates مع قائمة الشهادات المعدَّلة وcertificatesRequestId المستلَمة.

المعلمات

onSignatureRequested

الإصدار 86 من Chrome والإصدارات الأحدث 
chrome.certificateProvider.onSignatureRequested.addListener(
  callback: function,
)

يتم تشغيل هذا الحدث في كل مرة يحتاج فيها المتصفّح إلى توقيع رسالة باستخدام شهادة تقدّمها هذه الإضافة من خلال setCertificates.

يجب أن توقّع الإضافة بيانات الإدخال من request باستخدام الخوارزمية والمفتاح الخاص المناسبَين، وأن تعرضها من خلال استدعاء reportSignature مع signRequestId المستلَم.

المعلمات