chrome.platformKeys

الوصف

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

الأذونات

platformKeys

مدى التوفّر

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

الأنواع

ClientCertificateRequest

أماكن إقامة

  • certificateAuthorities

    ArrayBuffer[]

    قائمة بالأسماء المميزة للمراجع المصدقة التي يسمح بها الخادم. يجب أن يكون كل إدخال بترميز X.509 DistinguishedName بترميز DER.

  • certificateTypes

    ClientCertificateType[]

    هذا الحقل هو قائمة بأنواع الشهادات المطلوبة، ويتم ترتيبها بترتيب تفضيل الخادم. سيتم استرداد الشهادات من النوع الوارد في هذه القائمة فقط. إذا كانت القائمة certificateTypes هي القائمة الفارغة، سيتم عرض الشهادات من أي نوع.

ClientCertificateType

Enum

"rsaSign"

"ecdsaSign"

Match

أماكن إقامة

  • الشهادة

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

    ترميز DER لشهادة X.509

  • keyAlgorithm

    كائن

    KeyAlgorithm للمفتاح المعتمد. يحتوي هذا على مَعلمات الخوارزمية المتأصلة في مفتاح الشهادة (مثل طول المفتاح). ولم يتم تضمين معلَمات أخرى، مثل دالة التجزئة التي تستخدمها دالة الإشارة.

SelectDetails

أماكن إقامة

  • clientCerts

    ArrayBuffer[] اختيارية

    تعمل selectClientCertificates في هذه القائمة في حال توفّرها. بخلاف ذلك، سيحصل على قائمة بجميع الشهادات من مخازن شهادات النظام الأساسي المتاحة لهذه الإضافات. تتم إزالة الإدخالات التي لا تملك الإضافة إذنًا لها أو التي لا تتطابق مع الطلب.

  • تفاعلي

    منطقي

    في حال اختيار القيمة "true"، يتم تقديم القائمة التي تمت فلترتها للمستخدم لاختيار شهادة يدويًا، وبالتالي منح الإضافة إذن الوصول إلى الشهادات والمفاتيح. سيتم عرض الشهادات المحدّدة فقط. إذا تم ضبط السياسة على "خطأ"، يتم تقليل القائمة إلى جميع الشهادات التي تم منح الإضافة إذن الوصول إليها (تلقائيًا أو يدويًا).

  • لن يتم عرض سوى الشهادات التي تطابق هذا الطلب.

VerificationDetails

أماكن إقامة

  • اسم المضيف

    سلسلة

    اسم المضيف للخادم للتحقق من شهادته، على سبيل المثال: الخادم الذي قدّم serverCertificateChain.

  • serverCertificateChain

    ArrayBuffer[]

    يجب أن يكون كل إدخال سلسلة هو ترميز DER لشهادة X.509، ويجب أن يكون الإدخال الأول شهادة الخادم ويجب أن يصادق كل إدخال على الإدخال الذي يسبقه.

VerificationResult

أماكن إقامة

  • debug_errors

    سلسلة[]

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

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

  • موثوق به

    منطقي

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

الطُرق

getKeyPair()

chrome.platformKeys.getKeyPair(
  certificate: ArrayBuffer,
  parameters: object,
  callback: function,
)

تمرير مفتاحَي التشفير certificate للاستخدام مع platformKeys.subtleCrypto إلى callback

المعلمات

  • الشهادة

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

    شهادة Match التي أرجعها selectClientCertificates.

  • المعلمات

    كائن

    يحدد معلمات خوارزمية التوقيع/التجزئة بالإضافة إلى المعلمات التي تم إصلاحها بواسطة المفتاح نفسه. يتم قبول المعلمات نفسها بواسطة دالة importKey في WebCrypto، على سبيل المثال: RsaHashedImportParams للمفتاح RSASSA-PKCS1-v1_5 وEcKeyImportParams لمفتاح EC. بالإضافة إلى ذلك، بالنسبة إلى مفاتيح RSASSA-PKCS1-v1_5، يمكن تحديد معلَمة اسم خوارزمية التجزئة بإحدى القيم التالية: "none" أو "SHA-1" أو "SHA-256" أو "SHA-384" أو "SHA-512"، على سبيل المثال. {"hash": { "name": "none" } } ستعمل دالة التوقيع بعد ذلك على تطبيق المساحة المتروكة للإصدار 1.5 من PKCS#1 ولكن لن تجزئ البيانات المحددة.

    في الوقت الحالي، لا تتوافق هذه الطريقة إلا مع "RSASSA-PKCS1-v1_5" وECDSA الخوارزميات.

  • رد الاتصال

    دالة

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

    (publicKey: object, privateKey?: object) => void

    • publicKey

      كائن

    • privateKey

      الكائن اختياري

      قد تكون القيمة null إذا لم تتمكّن هذه الإضافة من الوصول إليها.

getKeyPairBySpki()

الإصدار 85 من Chrome أو الإصدارات الأحدث 
chrome.platformKeys.getKeyPairBySpki(
  publicKeySpkiDer: ArrayBuffer,
  parameters: object,
  callback: function,
)

تمرير مفتاحَي التشفير المحدَّدَين بواسطة publicKeySpkiDer للاستخدام مع platformKeys.subtleCrypto إلى callback

المعلمات

  • publicKeySpkiDer

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

    شهادة X.509 SubjectPublicKeyInfo بترميز DER، والتي تم الحصول عليها، على سبيل المثال: من خلال استدعاء دالة exportKey في WebCrypto باستخدام format="spki".

  • المعلمات

    كائن

    توفّر هذه البيانات معلَمات خوارزمية التجزئة والتوقيعات، بالإضافة إلى تلك التي تم تثبيتها بواسطة المفتاح نفسه. يتم قبول المعلمات نفسها بواسطة دالة importKey في WebCrypto، على سبيل المثال: RsaHashedImportParams للمفتاح RSASSA-PKCS1-v1_5. بالنسبة للمفاتيح RSASSA-PKCS1-v1_5، نحتاج أيضًا إلى تمرير "تجزئة" المعلمة { "hash": { "name": string } }. "التجزئة" اسم خوارزمية التجزئة المراد استخدامها في عملية الملخص قبل علامة. من الممكن تمرير "none" كاسم تجزئة، وفي هذه الحالة ستطبق دالة الإشارة المساحة المتروكة PKCS#1 v1.5 ولن تجزئ البيانات المحددة.

    في الوقت الحالي، تتوافق هذه الطريقة مع "ECDSA" خوارزمية ذات المنحنى المسمى P-256 و"RSASSA-PKCS1-v1_5" بإحدى خوارزميات التجزئة "none" و"SHA-1" و"SHA-256" و"SHA-384" و"SHA-512".

  • رد الاتصال

    دالة

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

    (publicKey: object, privateKey?: object) => void

    • publicKey

      كائن

    • privateKey

      الكائن اختياري

      قد تكون القيمة null إذا لم تتمكّن هذه الإضافة من الوصول إليها.

selectClientCertificates()

وعود 
chrome.platformKeys.selectClientCertificates(
  details: SelectDetails,
  callback?: function,
)

تؤدي هذه الطريقة إلى فلترة الشهادات من قائمة شهادات العميل المعروفة للمنصة، تتطابق مع request والتي يكون لدى الإضافة إذن لها بالوصول إلى الشهادة ومفتاحها الخاص. إذا تم ضبط السياسة interactive على "صحيح"، سيظهر للمستخدم مربّع حوار حيث يمكنه الاختيار من بين الشهادات المطابِقة ومنح الإضافة إذن الوصول إلى الشهادة. سيتم تمرير شهادات العميل المحدّدة/التي تمت فلترتها إلى callback.

المعلمات

  • التفاصيل

    SelectDetails

  • رد الاتصال

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

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

    (matches: Match[]) => void

    • فلتر مطابق لـ

      المطابقة[]

      قائمة الشهادات التي تطابق الطلب، والتي تمتلك الإضافة إذنًا لها، والتي يختارها المستخدم في حال كانت قيمة interactive صحيحة.

المرتجعات

  • الوعد <Match[]>

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

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

subtleCrypto()

chrome.platformKeys.subtleCrypto()

يشير هذا المصطلح إلى تنفيذ لترميز SubtleCrypto من WebCrypto يسمح بإجراء عمليات تشفير على مفاتيح شهادات العميل المتاحة لهذه الإضافة.

المرتجعات

  • object | غير محدّدة

verifyTLSServerCertificate()

وعود 
chrome.platformKeys.verifyTLSServerCertificate(
  details: VerificationDetails,
  callback?: function,
)

يتم التحقّق مما إذا كان يمكن الوثوق بـ details.serverCertificateChain في details.hostname وفقًا لإعدادات الثقة في النظام الأساسي. ملاحظة: لم يتم تحديد السلوك الفعلي لعملية "إثبات ملكية الثقة" بشكل كامل وقد يتغيّر في المستقبل. يتحقّق تنفيذ واجهة برمجة التطبيقات من انتهاء صلاحية الشهادة، ويتحقّق من مسار الشهادة، ويتحقّق من الثقة من قِبل مرجع تصديق معروف. من المفترض أن يراعي التنفيذ خادم EKU serverAuth وأن يتيح استخدام الأسماء البديلة للموضوع.

المعلمات

المرتجعات

  • Promise&lt;VerificationResult&gt;

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

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