الوصف
استخدِم واجهة برمجة التطبيقات هذه لعرض الشهادات على النظام الأساسي الذي يمكنه استخدام هذه الشهادات لمصادقات بروتوكول أمان طبقة النقل (TLS).
الأذونات
certificateProvider
مدى التوفّر
المفاهيم والاستخدام
إنّ الاستخدام النموذجي لواجهة برمجة التطبيقات هذه من أجل عرض شهادات العميل لنظام التشغيل ChromeOS يتبع الخطوات التالية:
- تُسجِّل الإضافة في الحدثَين
onCertificatesUpdateRequested
وonSignatureRequested
. - تطلب الإضافة
setCertificates()
لتقديم القائمة الأولية للشهادات بعد الإعداد. - تراقب الإضافة التغييرات في قائمة الشهادات والمكالمات المتاحة
setCertificates()
لإعلام المتصفّح بكل تغيير من هذا القبيل. - أثناء تأكيد اتصال بروتوكول أمان طبقة النقل (TLS)، يتلقّى المتصفِّح طلب شهادة عميل. في حدث
onCertificatesUpdateRequested
، يطلب المتصفّح من الإضافة الإبلاغ عن جميع الشهادات التي توفِّرها حاليًا. - ترسل الإضافة تقارير عن الشهادات المتاحة حاليًا باستخدام الطريقة
setCertificates()
. - يطابق المتصفِّح جميع الشهادات المتاحة مع طلب شهادة العميل من المضيف البعيد. يتم عرض النتائج المطابقة للمستخدم في مربّع حوار الاختيار.
- يمكن للمستخدم تحديد شهادة ومن ثم الموافقة على المصادقة أو إلغاء المصادقة.
![مربّع حوار اختيار الشهادة](https://developer.chrome.com/static/docs/extensions/reference/api/images/certificate_provider_selection_dialog.png?authuser=9&hl=ar)
- إذا ألغى المستخدم المصادقة أو لم تتطابق أي شهادة مع الطلب، سيتم إلغاء مصادقة عميل بروتوكول أمان طبقة النقل (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
أنواع خوارزميات التوقيعات المشفّرة المتوافقة.
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
أماكن إقامة
-
certificatesRequestId
الرقم
يمكنك إرسال المعرّف إلى
setCertificates
.
ClientCertificateInfo
أماكن إقامة
-
certificateChain
ArrayBuffer[]
يجب أن تحتوي المصفوفة على ترميز DER لشهادة العميل X.509 كعنصر أول لها.
يجب أن يتضمن هذا شهادة واحدة فقط.
-
supportedAlgorithms
جميع الخوارزميات المتوافقة مع هذه الشهادة. لن يُطلب من الإضافة التوقيعات إلا باستخدام إحدى هذه الخوارزميات.
Error
أنواع الأخطاء التي يمكن للإضافة الإبلاغ عنها.
القيمة
"GENERAL_ERROR"
Hash
تمّ الإيقاف. تم استبداله بـ Algorithm
.
Enum
"MD5_SHA1"
يحدد هذا الخيار خوارزميات التجزئة MD5 وSHA1.
"SHA1"
يحدد خوارزمية التجزئة SHA1.
"SHA256"
يحدد هذا الخيار خوارزمية التجزئة SHA256.
"SHA384"
يحدد هذا الخيار خوارزمية التجزئة SHA384.
"SHA512"
يحدد هذا الخيار خوارزمية التجزئة SHA512.
PinRequestErrorType
أنواع الأخطاء التي يمكن تقديمها إلى المستخدم من خلال دالة requestPin.
Enum
"KEY_PIN"
يحدد رقم التعريف الشخصي غير صالح.
"INSERT_PUK"
يحدد رمز PUK غير صالح.
"MAX_ATTEMPTS_EXCEEDED"
يحدد هذا الإعداد تم تجاوز الحد الأقصى لعدد المحاولات.
"UNKNOWN_ERROR"
يحدد هذا الحقل أنّه لا يمكن تمثيل الخطأ بالأنواع المذكورة أعلاه.
PinRequestType
تمثّل هذه السمة نوع الرمز الذي تطلبه الإضافة مع الدالة requestPin.
Enum
"رقم التعريف الشخصي"
يحدد الرمز المطلوب هو رقم تعريف شخصي.
"PUK"
يحدد الرمز المطلوب هو رمز PUK.
PinResponseDetails
أماكن إقامة
-
userInput
سلسلة اختيارية
تمثّل هذه السمة الرمز الذي يقدّمه المستخدم. يكون هذا الحقل فارغًا إذا أغلق المستخدم مربّع الحوار أو حدث خطأ آخر.
ReportSignatureDetails
أماكن إقامة
-
خطأ
"GENERAL_ERROR"
اختياريحدث خطأ أثناء إنشاء التوقيع، إن وُجد.
-
signRequestId
الرقم
معرّف الطلب الذي تم تلقّيه من خلال حدث
onSignatureRequested
-
توقيع
ArrayBuffer اختيارية
التوقيع، إذا تم إنشاؤه بنجاح.
RequestPinDetails
أماكن إقامة
-
attemptsLeft
الرقم اختياري
عدد المحاولات المتبقية ويتم توفير ذلك حتى تتمكّن أي واجهة مستخدم من عرض هذه المعلومات للمستخدم. من غير المتوقع أن يفرض Chrome ذلك، فبدلاً من ذلك يجب أن يتم استدعاءstopPinRequest من خلال الإضافة التي تحتوي على errorType = MAX_ATTEMPTS_EXCEEDED عند تجاوز عدد طلبات رقم التعريف الشخصي.
-
errorType
PinRequestErrorType optional
نموذج الخطأ الذي يتم عرضه للمستخدم يجب ضبط هذا الإعداد في حال تعذُّر الطلب السابق لإعلام المستخدم بسبب عدم نجاح العملية.
-
requestType
PinRequestType اختياري
نوع الرمز المطلوب. الإعداد التلقائي هو رقم التعريف الشخصي.
-
signRequestId
الرقم
رقم التعريف الذي يقدّمه Chrome في SignRequest.
SetCertificatesDetails
أماكن إقامة
-
certificatesRequestId
الرقم اختياري
عند استدعائها استجابةً للحقل
onCertificatesUpdateRequested
، يجب أن تحتوي على قيمةcertificatesRequestId
التي تم استلامها. وبخلاف ذلك، يجب إلغاء تحديده. -
clientCertificates
قائمة بشهادات العميل المتوفّرة حاليًا
-
خطأ
"GENERAL_ERROR"
اختياريحدث خطأ أثناء استخراج الشهادات، إن وُجدت. سيظهر هذا الخطأ للمستخدم عند الاقتضاء.
SignatureRequest
أماكن إقامة
-
خوارزمية
خوارزمية التوقيع المطلوب استخدامها.
-
الشهادة
مخزن المصفوفات
ترميز DER لشهادة X.509 يجب أن توقّع الإضافة
input
باستخدام المفتاح الخاص المرتبط بها. -
مصدر الإدخال
مخزن المصفوفات
البيانات المراد توقيعها. وتجدر الإشارة إلى أنّ البيانات غير مجزّأة.
-
signRequestId
الرقم
يمكنك إرسال المعرّف إلى
reportSignature
.
SignRequest
أماكن إقامة
-
الشهادة
مخزن المصفوفات
ترميز DER لشهادة X.509 يجب أن توقّع الإضافة
digest
باستخدام المفتاح الخاص المرتبط بها. -
سلسلة تمت تجزئتها
مخزن المصفوفات
الملخص الذي يجب توقيعه.
-
تجزئة
يشير إلى خوارزمية التجزئة التي تم استخدامها لإنشاء
digest
. -
signRequestId
الرقم
الإصدار 57 من Chrome أو الإصدارات الأحدثالمعرّف الفريد الذي تريد أن تستخدمه الإضافة في حال كان عليها طلب طريقة تتطلّبها، مثلاً: requestPin.
StopPinRequestDetails
أماكن إقامة
-
errorType
PinRequestErrorType optional
نموذج الخطأ وفي حال توفّرها، يتم عرضها للمستخدم. الغرض منها احتواء سبب إيقاف التدفق إذا كان ناتجًا عن خطأ، على سبيل المثال: MAX_ATTEMPTS_EXCEEDED.
-
signRequestId
الرقم
رقم التعريف الذي يقدّمه Chrome في SignRequest.
الطُرق
reportSignature()
chrome.certificateProvider.reportSignature(
details: ReportSignatureDetails,
callback?: function,
)
يجب استدعاؤه كرد على onSignatureRequested
.
يجب أن تطلب الإضافة هذه الدالة في النهاية لكل حدث onSignatureRequested
. سيتوقف تنفيذ واجهة برمجة التطبيقات عن انتظار هذا الاستدعاء بعد مرور بعض الوقت وسيستجيب مع ظهور خطأ انتهاء المهلة عند استدعاء هذه الدالة.
المعلمات
-
التفاصيل
-
رد الاتصال
الدالة اختيارية
تظهر المَعلمة
callback
على النحو التالي:() => void
المرتجعات
-
وعود <باطلة>
الإصدار 96 من Chrome أو الإصدارات الأحدثتتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير معاودة الاتصال. التوافق مع الأنظمة القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. تشير رسالة الأشكال البيانية يتم حل الوعد بنفس النوع الذي يتم إرساله إلى معاودة الاتصال.
requestPin()
chrome.certificateProvider.requestPin(
details: RequestPinDetails,
callback?: function,
)
تطلب رقم التعريف الشخصي من المستخدم. ويُسمح بإضافة طلب واحد مستمر فقط في كل مرة. ويتم رفض الطلبات الصادرة أثناء تنفيذ عملية أخرى. تقع على عاتق الإضافة مسؤولية إعادة المحاولة لاحقًا في حال كان هناك مسار آخر قيد التنفيذ.
المعلمات
-
التفاصيل
يحتوي على تفاصيل حول مربّع الحوار المطلوب.
-
رد الاتصال
الدالة اختيارية
تظهر المَعلمة
callback
على النحو التالي:(details?: PinResponseDetails) => void
-
التفاصيل
PinResponseDetails اختياري
-
المرتجعات
-
Promise<PinResponseDetails | غير محددة>
الإصدار 96 من Chrome أو الإصدارات الأحدثتتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير معاودة الاتصال. التوافق مع الأنظمة القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. تشير رسالة الأشكال البيانية يتم حل الوعد بنفس النوع الذي يتم إرساله إلى معاودة الاتصال.
setCertificates()
chrome.certificateProvider.setCertificates(
details: SetCertificatesDetails,
callback?: function,
)
لإعداد قائمة بالشهادات لاستخدامها في المتصفح
يجب أن تستدعي الإضافة هذه الدالة بعد الإعداد وعند كل تغيير في مجموعة الشهادات المتاحة حاليًا. يجب أن تستدعي الإضافة أيضًا هذه الدالة استجابةً لـ onCertificatesUpdateRequested
في كل مرة يتم فيها تلقّي هذا الحدث.
المعلمات
-
التفاصيل
الشهادات التي سيتم إعدادها. وسيتم تجاهل الشهادات غير الصالحة.
-
رد الاتصال
الدالة اختيارية
تظهر المَعلمة
callback
على النحو التالي:() => void
المرتجعات
-
وعود <باطلة>
الإصدار 96 من Chrome أو الإصدارات الأحدثتتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير معاودة الاتصال. التوافق مع الأنظمة القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. تشير رسالة الأشكال البيانية يتم حل الوعد بنفس النوع الذي يتم إرساله إلى معاودة الاتصال.
stopPinRequest()
chrome.certificateProvider.stopPinRequest(
details: StopPinRequestDetails,
callback?: function,
)
لإيقاف طلب رقم التعريف الشخصي الذي بدأته الدالة requestPin
.
المعلمات
-
التفاصيل
يحتوي على تفاصيل حول سبب إيقاف مسار الطلب.
-
رد الاتصال
الدالة اختيارية
تظهر المَعلمة
callback
على النحو التالي:() => void
المرتجعات
-
وعود <باطلة>
الإصدار 96 من Chrome أو الإصدارات الأحدثتتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير معاودة الاتصال. التوافق مع الأنظمة القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. تشير رسالة الأشكال البيانية يتم حل الوعد بنفس النوع الذي يتم إرساله إلى معاودة الاتصال.
فعاليات
onCertificatesRequested
chrome.certificateProvider.onCertificatesRequested.addListener(
callback: function,
)
يمكنك استخدام onCertificatesUpdateRequested
بدلاً من ذلك.
يتم تنشيط هذا الحدث في كل مرة يطلب فيها المتصفِّح القائمة الحالية للشهادات التي تقدِّمها هذه الإضافة. يجب أن تطلب الإضافة reportCallback
مرة واحدة بالضبط باستخدام قائمة الشهادات الحالية.
المعلمات
-
رد الاتصال
دالة
تظهر المَعلمة
callback
على النحو التالي:(reportCallback: function) => void
-
reportCallback
دالة
تظهر المَعلمة
reportCallback
على النحو التالي:(certificates: CertificateInfo[], callback: function) => void
-
الشهادات
-
رد الاتصال
دالة
تظهر المَعلمة
callback
على النحو التالي:(rejectedCertificates: ArrayBuffer[]) => void
-
rejectedCertificates
ArrayBuffer[]
-
-
-
onCertificatesUpdateRequested
chrome.certificateProvider.onCertificatesUpdateRequested.addListener(
callback: function,
)
يتم تنشيط هذا الحدث إذا كانت الشهادات التي تم ضبطها عبر setCertificates
غير كافية أو إذا طلب المتصفِّح معلومات محدَّثة. يجب أن تطلب الإضافة استدعاء setCertificates
مع قائمة الشهادات المُعدَّلة وcertificatesRequestId
المُستلَم.
المعلمات
-
رد الاتصال
دالة
تظهر المَعلمة
callback
على النحو التالي:(request: CertificatesUpdateRequest) => void
onSignatureRequested
chrome.certificateProvider.onSignatureRequested.addListener(
callback: function,
)
يتم تنشيط هذا الحدث في كل مرة يحتاج فيها المتصفِّح إلى توقيع رسالة باستخدام شهادة توفِّرها هذه الإضافة عبر setCertificates
.
يجب أن توقّع الإضافة على البيانات المدخلة من request
باستخدام الخوارزمية والمفتاح الخاص المناسبَين وتعرضها من خلال طلب reportSignature
باستخدام رمز signRequestId
الذي تم استلامه.
المعلمات
-
رد الاتصال
دالة
تظهر المَعلمة
callback
على النحو التالي:(request: SignatureRequest) => void
-
طلب
-
onSignDigestRequested
chrome.certificateProvider.onSignDigestRequested.addListener(
callback: function,
)
يمكنك استخدام onSignatureRequested
بدلاً من ذلك.
يتم تنشيط هذا الحدث في كل مرة يحتاج فيها المتصفِّح إلى توقيع رسالة باستخدام شهادة توفِّرها هذه الإضافة ردًا على حدث onCertificatesRequested
. يجب أن توقّع الإضافة على البيانات في "request
" باستخدام الخوارزمية والمفتاح الخاص المناسبَين وتعرضها من خلال طلب reportCallback
. يجب استدعاء reportCallback
مرة واحدة بالضبط.
المعلمات
-
رد الاتصال
دالة
تظهر المَعلمة
callback
على النحو التالي:(request: SignRequest, reportCallback: function) => void
-
طلب
-
reportCallback
دالة
الإصدار 47 من Chrome أو الإصدارات الأحدثتظهر المَعلمة
reportCallback
على النحو التالي:(signature?: ArrayBuffer) => void
-
توقيع
ArrayBuffer اختيارية
-
-