chrome.certificateProvider

الوصف

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

الأذونات

certificateProvider

مدى التوفّر

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

المفاهيم وطريقة الاستخدام

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

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

يمكن أن يختلف تسلسل الخطوات الفعلي. على سبيل المثال، لن يُطلب من المستخدم اختيار شهادة إذا تم استخدام سياسة المؤسسة لاختيار شهادة تلقائيًا (راجِع 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 والإصدارات الأحدث

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

تعداد

‫"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

    التجزئة[]

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

CertificatesUpdateRequest

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

الخصائص

  • certificatesRequestId

    الرقم

    يجب تمرير معرّف الطلب إلى setCertificates.

ClientCertificateInfo

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

الخصائص

  • certificateChain

    ArrayBuffer[]

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

    يجب أن يتضمّن هذا الإجراء شهادة واحدة فقط.

  • supportedAlgorithms

    الخوارزمية[]

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

Error

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

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

القيمة

"GENERAL_ERROR"

Hash

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

تعداد

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

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

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

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

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

PinRequestErrorType

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

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

تعداد

‫"INVALID_PIN"
تشير إلى أنّ رقم التعريف الشخصي غير صالح.

‫"INVALID_PUK"
تشير إلى أنّ رمز PUK غير صالح.

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

‫"UNKNOWN_ERROR"
تشير إلى أنّه لا يمكن تمثيل الخطأ بالأنواع المذكورة أعلاه.

PinRequestType

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

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

تعداد

‫"PIN"
تشير إلى أنّ الرمز المطلوب هو رقم تعريف شخصي.

‫"PUK"
تشير إلى أنّ الرمز المطلوب هو رمز PUK.

PinResponseDetails

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

الخصائص

  • userInput

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

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

ReportSignatureDetails

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

الخصائص

  • خطأ

    "GENERAL_ERROR"
     اختياري

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

  • signRequestId

    الرقم

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

  • توقيع

    ArrayBuffer اختياري

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

RequestPinDetails

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

الخصائص

  • attemptsLeft

    رقم اختياري

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

  • errorType

    ‫PinRequestErrorType اختياري

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

  • requestType

    ‫PinRequestType اختياري

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

  • signRequestId

    الرقم

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

SetCertificatesDetails

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

الخصائص

  • certificatesRequestId

    رقم اختياري

    عند استدعائه استجابةً لطلب onCertificatesUpdateRequested، يجب أن يحتوي على قيمة certificatesRequestId المستلَمة. وبخلاف ذلك، يجب عدم ضبطه.

  • clientCertificates

    ClientCertificateInfo[]

    قائمة بشهادات العميل المتاحة حاليًا

  • خطأ

    "GENERAL_ERROR"
     اختياري

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

SignatureRequest

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

الخصائص

  • خوارزمية

    الخوارزمية

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

  • الشهادة

    ArrayBuffer

    ترميز DER لشهادة X.509 يجب أن يوقّع الملحق على 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,
  callback?: function,
)

يجب استدعاؤه استجابةً لـ onSignatureRequested.

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

المعلمات

  • التفاصيل

    ReportSignatureDetails

  • ردّ الاتصال

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    () => void

المرتجعات

  • Promise<void>

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

    تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير طلبات الاستدعاء لأجل التوافق مع الإصدارات القديمة. ولا يمكنك استخدام كليهما في طلب الدالة نفسه. يتم حلّ الوعد بالنوع نفسه الذي يتم تمريره إلى دالة الاستدعاء.

requestPin()

الوعد Chrome 57 والإصدارات الأحدث 
chrome.certificateProvider.requestPin(
  details: RequestPinDetails,
  callback?: function,
)

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

المعلمات

  • التفاصيل

    RequestPinDetails

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

  • ردّ الاتصال

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    (details?: PinResponseDetails) => void

المرتجعات

  • Promise<PinResponseDetails | undefined>

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

    تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير طلبات الاستدعاء لأجل التوافق مع الإصدارات القديمة. ولا يمكنك استخدام كليهما في طلب الدالة نفسه. يتم حلّ الوعد بالنوع نفسه الذي يتم تمريره إلى دالة الاستدعاء.

setCertificates()

الوعد الإصدار 86 من Chrome والإصدارات الأحدث 
chrome.certificateProvider.setCertificates(
  details: SetCertificatesDetails,
  callback?: function,
)

لضبط قائمة بالشهادات المطلوب استخدامها في المتصفّح

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

المعلمات

  • التفاصيل

    SetCertificatesDetails

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

  • ردّ الاتصال

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    () => void

المرتجعات

  • Promise<void>

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

    تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير طلبات الاستدعاء لأجل التوافق مع الإصدارات القديمة. ولا يمكنك استخدام كليهما في طلب الدالة نفسه. يتم حلّ الوعد بالنوع نفسه الذي يتم تمريره إلى دالة الاستدعاء.

stopPinRequest()

الوعد Chrome 57 والإصدارات الأحدث 
chrome.certificateProvider.stopPinRequest(
  details: StopPinRequestDetails,
  callback?: function,
)

يوقف طلب تثبيت العلامة الذي بدأته الدالة requestPin.

المعلمات

  • التفاصيل

    StopPinRequestDetails

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

  • ردّ الاتصال

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    () => void

المرتجعات

  • Promise<void>

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

    تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير طلبات الاستدعاء لأجل التوافق مع الإصدارات القديمة. ولا يمكنك استخدام كليهما في طلب الدالة نفسه. يتم حلّ الوعد بالنوع نفسه الذي يتم تمريره إلى دالة الاستدعاء.

الفعاليات

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 المستلَم.

المعلمات

  • ردّ الاتصال

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    (request: SignatureRequest) => void