chrome.certificateProvider

الوصف

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

الخصائص

  • الشهادة

    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

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

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

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

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

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

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

المعلمات

المرتجعات

  • Promise<void>

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

requestPin()

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

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

المعلمات

  • التفاصيل

    RequestPinDetails

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

المرتجعات

  • Promise<PinResponseDetails | undefined>

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

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

setCertificates()

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

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

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

المعلمات

  • التفاصيل

    SetCertificatesDetails

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

المرتجعات

  • Promise<void>

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

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

stopPinRequest()

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

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

المعلمات

  • التفاصيل

    StopPinRequestDetails

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

المرتجعات

  • Promise<void>

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

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

الفعاليات

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

المعلمات