chrome.certificateProvider

refresh date: 2026-09-25 robots: noindex

الوصف

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

الأذونات

certificateProvider

مدى التوفّر

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

الاستخدام

يتّبع الاستخدام المعتاد لواجهة برمجة التطبيقات هذه لعرض شهادات العميل على 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 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 والإصدارات الأحدث

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

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

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

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

Error

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

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

القيمة

"GENERAL_ERROR"

Hash

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

Enum

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

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

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

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

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

PinRequestErrorType

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

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

Enum

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

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

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

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

PinRequestType

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

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

Enum

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

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

PinResponseDetails

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

الخصائص

  • userInput

    string اختياري

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

ReportSignatureDetails

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

الخصائص

  • خطأ

    "GENERAL_ERROR"
     اختيارية

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

  • signRequestId

    الرقم

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

  • التوقيع

    ‫ArrayBuffer اختياري

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

RequestPinDetails

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

الخصائص

  • 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

    الرقم

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

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

StopPinRequestDetails

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

الخصائص

  • errorType

    PinRequestErrorType اختياري

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

  • signRequestId

    الرقم

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

الطُرق

reportSignature()

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

يجب استدعاؤها كردّ على onSignatureRequested.

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

المعلمات

  • التفاصيل

    ReportSignatureDetails

  • callback

    function اختياري

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

    () => void

المرتجعات

  • وعد<فراغ>

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

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

requestPin()

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

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

المعلمات

  • التفاصيل

    RequestPinDetails

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

  • callback

    function اختياري

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

    (details?: PinResponseDetails) => void

المرتجعات

  • Promise<PinResponseDetails | undefined>

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

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

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

setCertificates()

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

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

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

المعلمات

  • التفاصيل

    SetCertificatesDetails

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

  • callback

    function اختياري

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

    () => void

المرتجعات

  • وعد<فراغ>

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

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

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

stopPinRequest()

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

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

المعلمات

  • التفاصيل

    StopPinRequestDetails

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

  • callback

    function اختياري

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

    () => void

المرتجعات

  • وعد<فراغ>

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

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

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

الفعاليات

onCertificatesRequested

الإصدار 47 من Chrome والإصدارات الأحدث &leq; الإصدار 2 من بيان الإضافة تم إيقافها نهائيًا منذ الإصدار 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; MV2 تم الإيقاف نهائيًا منذ الإصدار 86 من Chrome
chrome.certificateProvider.onSignDigestRequested.addListener(
  callback: function,
)

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

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

المعلمات

  • callback

    دالة

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

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

    • طلب

      SignRequest

    • reportCallback

      دالة

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

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

      (signature?: ArrayBuffer) => void

      • التوقيع

        ‫ArrayBuffer اختياري