chrome.certificateProvider

الوصف

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

الأذونات

certificateProvider

مدى توفّر الخدمة

Chrome 46 والإصدارات الأحدث ChromeOS فقط

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

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

  • يتم تسجيل الإضافة للحدثَين onCertificatesUpdateRequested وonSignatureRequested.
  • تطلب الإضافة setCertificates() لتقديم القائمة الأولية بالشهادات بعد الإعداد.
  • تراقب الإضافة التغييرات في قائمة الشهادات المتاحة وتطلب setCertificates() إشعار المتصفِّح بكلّ تغيير من هذا القبيل.
  • أثناء تأكيد اتصال بروتوكول أمان طبقة النقل (TLS)، يتلقّى المتصفّح طلب شهادة عميل. عند استخدام حدث 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

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

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

التعداد

"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

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

أماكن إقامة

  • certificatesRequestId

    الرقم

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

ClientCertificateInfo

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

أماكن إقامة

  • certificateChain

    ArrayBuffer[]

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

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

  • supportedAlgorithms

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

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

Error

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

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

القيمة

"GENERAL_ERROR"

Hash

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

التعداد

"MD5_SHA1"
يحدد هذا الإعداد خوارزميات التجزئة MD5 وSHA1.

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

"SHA256"
يحدد هذا الإعداد خوارزمية التجزئة SHA256.

"SHA384"
يحدد هذا الإعداد خوارزمية التجزئة SHA384.

"SHA512"
يحدد هذا الإعداد خوارزمية التجزئة SHA512.

PinRequestErrorType

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

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

التعداد

"NEW_PIN"
تحديد رقم التعريف الشخصي غير صالح.

"POINTS_PUK"
تحديد رمز PUK غير صالح.

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

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

PinRequestType

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

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

التعداد

"رقم التعريف الشخصي"
يحدّد الرمز المطلوب رقم تعريف شخصي.

"PUK"
يحدّد الرمز المطلوب هو رمز PUK.

PinResponseDetails

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

أماكن إقامة

  • userInput

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

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

ReportSignatureDetails

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

أماكن إقامة

  • خطأ

     اختياري

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

  • signRequestId

    الرقم

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

  • signature

    ArrayBuffer اختيارية

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

RequestPinDetails

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

أماكن إقامة

  • attemptsLeft

    الرقم اختياري

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

  • errorType

    PinRequestErrorType اختيارية

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

  • requestType

    PinRequestType اختياري

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

  • signRequestId

    الرقم

    المعرّف المقدَّم من Chrome في SignRequest.

SetCertificatesDetails

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

أماكن إقامة

  • certificatesRequestId

    الرقم اختياري

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

  • clientCertificates

    ClientCertificateInfo[]

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

  • خطأ

     اختياري

    حدث خطأ أثناء استخراج الشهادات، في حال حدوثها. سيظهر هذا الخطأ للمستخدم عندما يكون ذلك مناسبًا.

SignatureRequest

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

أماكن إقامة

  • خوارزمية

    الخوارزمية

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

  • الشهادة

    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

المرتجعات

  • الوعد<PinResponseDetails|غير محدّدة>

    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 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.

فعاليات

onCertificatesRequested

Chrome 47 والإصدارات الأحدث &leq; MV2 الإيقاف منذ Chrome 86
chrome.certificateProvider.onCertificatesRequested.addListener(
  callback: function,
)

يمكنك استخدام onCertificatesUpdateRequested بدلاً منها.

يتم تنشيط هذا الحدث في كل مرة يطلب فيها المتصفِّح القائمة الحالية للشهادات التي توفّرها هذه الإضافة. يجب أن تطلب الإضافة reportCallback مرة واحدة فقط مع قائمة الشهادات الحالية.

المَعلمات

  • معاودة الاتصال

    الوظيفة

    تبدو معلَمة callback على النحو التالي: 

    (reportCallback: function)=>void

    • reportCallback

      الوظيفة

      تبدو معلَمة reportCallback على النحو التالي: 

      (certificates: CertificateInfo[],callback: function)=>void

      • الشهادات

        CertificateInfo[]

      • معاودة الاتصال

        الوظيفة

        تبدو معلَمة callback على النحو التالي: 

        (rejectedCertificates: ArrayBuffer[])=>void

        • rejectedCertificates

          ArrayBuffer[]

onCertificatesUpdateRequested

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

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

المَعلمات

onSignatureRequested

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

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

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

المَعلمات

  • معاودة الاتصال

    الوظيفة

    تبدو معلَمة callback على النحو التالي: 

    (request: SignatureRequest)=>void

onSignDigestRequested

&leq; MV2 تم إيقافه منذ Chrome 86
chrome.certificateProvider.onSignDigestRequested.addListener(
  callback: function,
)

يمكنك استخدام onSignatureRequested بدلاً منها.

يتم تنشيط هذا الحدث في كل مرة يحتاج فيها المتصفِّح إلى توقيع رسالة باستخدام شهادة مقدَّمة من هذه الإضافة ردًا على حدث onCertificatesRequested. يجب أن توقّع الإضافة البيانات في request باستخدام الخوارزمية والمفتاح الخاص المناسبَين ثم تُرجعها من خلال طلب reportCallback. يجب طلب الاتصال بـ "reportCallback" مرة واحدة بالضبط.

المَعلمات

  • معاودة الاتصال

    الوظيفة

    تبدو معلَمة callback على النحو التالي: 

    (request: SignRequest,reportCallback: function)=>void

    • طلب

      SignRequest

    • reportCallback

      الوظيفة

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

      تبدو معلَمة reportCallback على النحو التالي: 

      (signature?: ArrayBuffer)=>void

      • signature

        ArrayBuffer اختيارية