chrome.certificateProvider

refresh date: 2026-09-25 robots: noindex

الوصف

استخدِم واجهة برمجة التطبيقات هذه لعرض الشهادات على النظام الأساسي الذي يمكنه استخدام هذه الشهادات للمصادقة على بروتوكول أمان طبقة النقل (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 not 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

    Hash[]

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

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

    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 باستخدام المفتاح الخاص المرتبط بها.

  • إدخال

    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()

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

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

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

المعلمات

  • التفاصيل

    ReportSignatureDetails

  • callback

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

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

    () => void

المرتجعات

  • Promise<void>

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

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

requestPin()

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

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

المعلمات

  • التفاصيل

    RequestPinDetails

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

  • callback

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

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

    (details?: PinResponseDetails) => void

المرتجعات

  • Promise<PinResponseDetails | undefined>

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

    تعرض هذه الطريقة Promise يتم تنفيذه عند تقديم المستخدم لرقم التعريف الشخصي. يتم رفض الطلب مع ظهور خطأ إذا انتهى طلب مربّع الحوار بدون نجاح (على سبيل المثال، إذا ألغى المستخدم مربّع الحوار أو لم يُسمح بعرضه).

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

setCertificates()

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

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

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

المعلمات

  • التفاصيل

    SetCertificatesDetails

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

  • callback

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

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

    () => void

المرتجعات

  • Promise<void>

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

    تعرض هذه الطريقة Promise يتم تنفيذه عند اكتمال العملية.

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

stopPinRequest()

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

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

المعلمات

  • التفاصيل

    StopPinRequestDetails

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

  • callback

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

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

    () => void

المرتجعات

  • Promise<void>

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

    تعرض هذه الطريقة Promise يتم تنفيذه عند اكتمال طلب إغلاق مربّع حوار رقم التعريف الشخصي.

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

الفعاليات

onCertificatesRequested

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

استخدِم onCertificatesUpdateRequested بدلاً من ذلك.

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

المعلمات

  • callback

    دالة

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

    (reportCallback: function) => void

    • reportCallback

      دالة

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

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

      • الشهادات

        CertificateInfo[]

      • callback

        دالة

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

        (rejectedCertificates: ArrayBuffer[]) => void

        • rejectedCertificates

          ArrayBuffer[]

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

المعلمات

onSignDigestRequested

&leq; الإصدار 2 من Manifest تم إيقافه نهائيًا منذ الإصدار 86 من Chrome
chrome.certificateProvider.onSignDigestRequested.addListener(
  callback: function,
)

استخدِم onSignatureRequested بدلاً من ذلك.

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

المعلمات

  • callback

    دالة

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

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

    • طلب

      SignRequest

    • reportCallback

      دالة

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

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

      (signature?: ArrayBuffer) => void

      • التوقيع

        ‫ArrayBuffer اختياري