الوصف
استخدِم واجهة برمجة التطبيقات هذه لعرض الشهادات على النظام الأساسي الذي يمكنه استخدام هذه الشهادات لمصادقات بروتوكول أمان طبقة النقل (TLS).
الأذونات
certificateProvider
مدى التوفّر
الاستخدام
يتّبع الاستخدام المعتاد لواجهة برمجة التطبيقات هذه لعرض شهادات العميل لنظام التشغيل 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
أنواع خوارزميات التوقيعات المشفّرة المتوافقة.
التعداد
"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
تجزئة[]
يجب ضبطها على جميع علامات التجزئة المتوافقة مع هذه الشهادة. سيُطلب من هذه الإضافة إدخال توقيعات الملخصات المحسوبة باستخدام إحدى خوارزميات التجزئة هذه. ويجب أن يكون هذا من أجل تقليل تفضيل التجزئة.
CertificatesUpdateRequest
أماكن إقامة
-
certificatesRequestId
الرقم
معرّف الطلب الذي يجب تمريره إلى
setCertificates
.
ClientCertificateInfo
أماكن إقامة
-
certificateChain
ArrayBuffer[]
يجب أن تحتوي الصفيفة على ترميز DER لشهادة العميل X.509 كعنصر أول.
يجب أن يتضمن هذا شهادة واحدة فقط.
-
supportedAlgorithms
جميع الخوارزميات المتوافقة مع هذه الشهادة. سيُطلب من الإضافة توقيعات باستخدام إحدى هذه الخوارزميات فقط.
Error
أنواع الأخطاء التي يمكن أن تُبلغ عنها الإضافة.
القيمة
"GENERAL_ERROR"
Hash
تمّ الإيقاف. تم استبداله بـ Algorithm
.
التعداد
"MD5_SHA1"
يحدد هذا الإعداد خوارزميات التجزئة MD5 وSHA1.
"SHA1"
يحدد خوارزمية التجزئة SHA1.
"SHA256"
يحدد هذا الإعداد خوارزمية التجزئة SHA256.
"SHA384"
يحدد هذا الإعداد خوارزمية التجزئة SHA384.
"SHA512"
يحدد هذا الإعداد خوارزمية التجزئة SHA512.
PinRequestErrorType
أنواع الأخطاء التي يمكن تقديمها للمستخدم من خلال دالة requestPin
التعداد
"NEW_PIN"
تحديد رقم التعريف الشخصي غير صالح.
"POINTS_PUK"
تحديد رمز PUK غير صالح.
"MAX_ATTEMPTS_EXCEEDED"
يحدد هذا الخيار الحد الأقصى لعدد المحاولات التي تم تجاوزها.
"UNKNOWN_ERROR"
يحدد هذا الحقل أنّه لا يمكن تمثيل الخطأ من خلال الأنواع المذكورة أعلاه.
PinRequestType
تمثّل هذه السمة نوع الرمز الذي تطلبه الإضافة مع دالة requestPin.
التعداد
"رقم التعريف الشخصي"
يحدّد الرمز المطلوب رقم تعريف شخصي.
"PUK"
يحدّد الرمز المطلوب هو رمز PUK.
PinResponseDetails
أماكن إقامة
-
userInput
سلسلة اختيارية
الرمز الذي قدَّمه المستخدم هذا الحقل فارغ إذا أغلق المستخدم مربّع الحوار أو حدث خطأ آخر.
ReportSignatureDetails
أماكن إقامة
-
خطأ
اختياري
حدث خطأ أثناء إنشاء التوقيع، إن وجد.
-
signRequestId
الرقم
معرّف الطلب الذي تم تلقّيه من خلال حدث
onSignatureRequested
. -
signature
ArrayBuffer اختيارية
التوقيع، إذا تم إنشاؤه بنجاح.
RequestPinDetails
أماكن إقامة
-
attemptsLeft
الرقم اختياري
عدد المحاولات المتبقية. يتم توفير ذلك بحيث يمكن لأي واجهة مستخدم تقديم هذه المعلومات للمستخدم. ليس من المتوقع أن يفرض Chrome هذا، وبدلاً من ذلك، يجب أن يتم استدعاء StopPinRequest بواسطة الإضافة التي تحتوي على errorType = MAX_ATTEMPTS_EXCEEDED عند تجاوز عدد طلبات رقم التعريف الشخصي.
-
errorType
PinRequestErrorType اختيارية
نموذج الخطأ المعروض للمستخدم يجب ضبط هذه السياسة في حال تعذّر الطلب السابق، لإشعار المستخدم بسبب عدم التنفيذ.
-
requestType
PinRequestType اختياري
نوع الرمز المطلوب الإعداد التلقائي هو رقم التعريف الشخصي.
-
signRequestId
الرقم
المعرّف المقدَّم من Chrome في SignRequest.
SetCertificatesDetails
أماكن إقامة
-
certificatesRequestId
الرقم اختياري
عند طلب البيانات استجابةً للسمة
onCertificatesUpdateRequested
، يجب أن تحتوي على القيمةcertificatesRequestId
التي تم تلقّيها. وبخلاف ذلك، يجب إلغاء الضبط. -
clientCertificates
قائمة بشهادات العملاء المتاحة حاليًا
-
خطأ
اختياري
حدث خطأ أثناء استخراج الشهادات، في حال حدوثها. سيظهر هذا الخطأ للمستخدم عندما يكون ذلك مناسبًا.
SignatureRequest
أماكن إقامة
-
خوارزمية
خوارزمية التوقيع التي سيتم استخدامها.
-
الشهادة
ArrayBuffer
ترميز DER لشهادة X.509. يجب أن توقّع الإضافة
input
باستخدام المفتاح الخاص المرتبط بها. -
مصدر الإدخال
ArrayBuffer
البيانات التي سيتمّ توقيعها ويُرجى العلم بأنّ البيانات لا تتم تجزئتها.
-
signRequestId
الرقم
معرّف الطلب الذي يجب تمريره إلى
reportSignature
.
SignRequest
أماكن إقامة
-
الشهادة
ArrayBuffer
ترميز DER لشهادة X.509. يجب أن توقّع الإضافة
digest
باستخدام المفتاح الخاص المرتبط بها. -
سلسلة تمت تجزئتها
ArrayBuffer
الملخّص الذي يجب توقيعه.
-
تجزئة
يشير هذا المصطلح إلى خوارزمية التجزئة التي تم استخدامها لإنشاء
digest
. -
signRequestId
الرقم
Chrome 57 والإصدارات الأحدثالمعرّف الفريد الذي تريد أن تستخدمه الإضافة إذا لزم الأمر لطلب طريقة تتطلب ذلك، مثل requestPin.
StopPinRequestDetails
أماكن إقامة
-
errorType
PinRequestErrorType اختيارية
نموذج الخطأ وفي حال توفّرها، سيتم عرضها للمستخدم. يُقصد بها احتواء سبب إيقاف التدفق إذا كان ناتجًا عن خطأ، على سبيل المثال MAX_ATTEMPTS_EXCEEDED.
-
signRequestId
الرقم
المعرّف المقدَّم من Chrome في SignRequest.
الطُرق
reportSignature()
chrome.certificateProvider.reportSignature(
details: ReportSignatureDetails,
callback?: function,
)
يجب أن يتم استدعاؤه كردّ على onSignatureRequested
.
يجب أن تستدعي الإضافة هذه الدالة في النهاية لكل حدث onSignatureRequested
، وسيتوقّف تنفيذ واجهة برمجة التطبيقات عن انتظار هذا الطلب بعد مرور بعض الوقت وسيستجيب مع ظهور خطأ انتهاء المهلة عند استدعاء هذه الدالة.
المَعلمات
-
التفاصيل
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:() => void
المرتجعات
-
Promise<void>
Chrome 96 والإصدارات الأحدثلا تتوفّر الوعود إلا في الإصدار 3 من Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.
requestPin()
chrome.certificateProvider.requestPin(
details: RequestPinDetails,
callback?: function,
)
تطلب هذه الرسالة رقم التعريف الشخصي من المستخدم. يُسمح بإجراء طلب واحد حالي فقط في كل مرة. ويتم رفض الطلبات التي تم إصدارها خلال فترة استمرار تدفق آخر. تقع على عاتق الإضافة مسؤولية إعادة المحاولة لاحقًا إذا كان هناك مسار آخر قيد التنفيذ.
المَعلمات
-
التفاصيل
يحتوي على تفاصيل حول مربّع الحوار المطلوب.
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(details?: PinResponseDetails) => void
-
التفاصيل
PinResponseDetails اختيارية
-
المرتجعات
-
Promise<PinResponseDetails | undefined>
Chrome 96 والإصدارات الأحدثلا تتوفّر الوعود إلا في الإصدار 3 من Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.
setCertificates()
chrome.certificateProvider.setCertificates(
details: SetCertificatesDetails,
callback?: function,
)
تتيح هذه السياسة ضبط قائمة بالشهادات المطلوب استخدامها في المتصفِّح.
ومن المفترض أن تستدعي الإضافة هذه الدالة بعد الإعداد وعند كل تغيير في مجموعة الشهادات المتاحة حاليًا. يجب أن تستدعي الإضافة هذه الدالة أيضًا استجابةً للحقل onCertificatesUpdateRequested
في كل مرة يتم فيها تلقّي هذا الحدث.
المَعلمات
-
التفاصيل
الشهادات المطلوب ضبطها. سيتم تجاهل الشهادات غير الصالحة.
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:() => void
المرتجعات
-
Promise<void>
Chrome 96 والإصدارات الأحدثلا تتوفّر الوعود إلا في الإصدار 3 من Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.
stopPinRequest()
chrome.certificateProvider.stopPinRequest(
details: StopPinRequestDetails,
callback?: function,
)
يتم إيقاف طلب التثبيت الذي بدأته الدالة requestPin
.
المَعلمات
-
التفاصيل
يحتوي على تفاصيل حول سبب إيقاف تدفق الطلب.
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:() => void
المرتجعات
-
Promise<void>
Chrome 96 والإصدارات الأحدثلا تتوفّر الوعود إلا في الإصدار 3 من 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
الوظيفة
Chrome 47 والإصدارات الأحدثتبدو معلَمة
reportCallback
على النحو التالي:(signature?: ArrayBuffer) => void
-
signature
ArrayBuffer اختيارية
-
-