chrome.certificateProvider

الوصف

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

الأذونات

certificateProvider

مدى التوفّر

الإصدار 46 من Chrome أو الإصدارات الأحدث نظام التشغيل 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

الإصدار 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

أماكن إقامة

  • الشهادة

    مخزن المصفوفات

    يجب أن يكون ترميز 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.

Enum

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

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

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

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

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

PinRequestErrorType

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

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

Enum

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

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

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

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

PinRequestType

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

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

Enum

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

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

PinResponseDetails

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

أماكن إقامة

  • userInput

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

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

ReportSignatureDetails

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

أماكن إقامة

  • خطأ

    "GENERAL_ERROR"
     اختياري

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

  • signRequestId

    الرقم

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

  • توقيع

    ArrayBuffer اختيارية

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

RequestPinDetails

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

أماكن إقامة

  • attemptsLeft

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

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

  • errorType

    PinRequestErrorType optional

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

  • requestType

    PinRequestType اختياري

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

  • signRequestId

    الرقم

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

SetCertificatesDetails

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

أماكن إقامة

  • certificatesRequestId

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

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

  • clientCertificates

    ClientCertificateInfo[]

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

  • خطأ

    "GENERAL_ERROR"
     اختياري

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

SignatureRequest

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

أماكن إقامة

  • خوارزمية

    الخوارزمية

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

  • الشهادة

    مخزن المصفوفات

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

  • مصدر الإدخال

    مخزن المصفوفات

    البيانات المراد توقيعها. وتجدر الإشارة إلى أنّ البيانات غير مجزّأة.

  • signRequestId

    الرقم

    يمكنك إرسال المعرّف إلى reportSignature.

SignRequest

أماكن إقامة

  • الشهادة

    مخزن المصفوفات

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

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

    مخزن المصفوفات

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

  • تجزئة

    التجزئة

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

  • signRequestId

    الرقم

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

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

StopPinRequestDetails

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

أماكن إقامة

  • errorType

    PinRequestErrorType optional

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

  • signRequestId

    الرقم

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

الطُرق

reportSignature()

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

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

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

المعلمات

  • التفاصيل

    ReportSignatureDetails

  • رد الاتصال

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

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

    () => void

المرتجعات

  • وعود <باطلة>

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

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

requestPin()

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

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

المعلمات

  • التفاصيل

    RequestPinDetails

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

  • رد الاتصال

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

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

    (details?: PinResponseDetails) => void

المرتجعات

  • Promise&lt;PinResponseDetails | غير محددة>

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

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

setCertificates()

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

لإعداد قائمة بالشهادات لاستخدامها في المتصفح

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

المعلمات

  • التفاصيل

    SetCertificatesDetails

    الشهادات التي سيتم إعدادها. وسيتم تجاهل الشهادات غير الصالحة.

  • رد الاتصال

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

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

    () => void

المرتجعات

  • وعود <باطلة>

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

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

stopPinRequest()

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

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

المعلمات

  • التفاصيل

    StopPinRequestDetails

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

  • رد الاتصال

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

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

    () => void

المرتجعات

  • وعود <باطلة>

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

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

فعاليات

onCertificatesRequested

الإصدار 47 من Chrome أو الإصدارات الأحدث &amp;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

الإصدار 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

onSignDigestRequested

&amp;leq; MV2 متوقّف منذ إصدار Chrome 86
chrome.certificateProvider.onSignDigestRequested.addListener(
  callback: function,
)

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

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

المعلمات

  • رد الاتصال

    دالة

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

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

    • طلب

      SignRequest

    • reportCallback

      دالة

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

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

      (signature?: ArrayBuffer) => void

      • توقيع

        ArrayBuffer اختيارية