chrome.enterprise.platformKeys

الوصف

استخدِم واجهة برمجة التطبيقات chrome.enterprise.platformKeys لإنشاء مفاتيح وتثبيت شهادات لهذه المفاتيح. سيدير النظام الأساسي الشهادات ويمكن استخدامها لمصادقة بروتوكول أمان طبقة النقل (TLS) أو الوصول إلى الشبكة أو بواسطة إضافة أخرى من خلال chrome.platformKeys.

الأذونات

enterprise.platformKeys

مدى التوفّر

نظام التشغيل ChromeOS فقط تتطلّب سياسة

الاستخدام

يتم عادةً استخدام واجهة برمجة التطبيقات هذه لتسجيل شهادة عميل باتّباع الخطوات التالية:

  • احصل على جميع الرموز المميزة المتاحة باستخدام enterprise.platformKeys.getTokens.

  • ابحث عن الرمز المميّز الذي تكون فيه قيمة id مساوية "user". استخدِم هذا الرمز المميّز لاحقًا.

  • أنشئ زوجًا من المفاتيح باستخدام generateKey طريقة الرمز المميز (المحدّدة في SubtleCrypto). سيؤدي ذلك إلى عرض معرّف المفتاح.

  • صدِّر المفتاح العام باستخدام exportKey طريقة الرمز المميز (المحدّدة في SubtleCrypto).

  • أنشئ توقيعًا لبيانات طلب شهادة الاعتماد باستخدام طريقة الرمز المميز sign (المحدّدة في SubtleCrypto).

  • أكمِل طلب الحصول على شهادة الاعتماد وأرسِله إلى هيئة إصدار الشهادات.

  • في حال تلقّي شهادة، استورِدها باستخدام enterprise.platformKeys.importCertificate

في ما يلي مثال يعرض التفاعل الرئيسي مع واجهة برمجة التطبيقات باستثناء إنشاء طلب الشهادة وإرساله:

function getUserToken(callback) {   chrome.enterprise.platformKeys.getTokens(function(tokens) {     for (var i = 0; i < tokens.length; i++) {       if (tokens[i].id == "user") {         callback(tokens[i]);         return;       }     }     callback(undefined);   }); }  function generateAndSign(userToken) {   var data = new Uint8Array([0, 5, 1, 2, 3, 4, 5, 6]);   var algorithm = {     name: "RSASSA-PKCS1-v1_5",     // RsaHashedKeyGenParams     modulusLength: 2048,     publicExponent:         new Uint8Array([0x01, 0x00, 0x01]),  // Equivalent to 65537     hash: {       name: "SHA-256",     }   };   var cachedKeyPair;   userToken.subtleCrypto.generateKey(algorithm, false, ["sign"])     .then(function(keyPair) {             cachedKeyPair = keyPair;             return userToken.subtleCrypto.exportKey("spki", keyPair.publicKey);           },           console.log.bind(console))     .then(function(publicKeySpki) {             // Build the Certification Request using the public key.             return userToken.subtleCrypto.sign(                 {name : "RSASSA-PKCS1-v1_5"}, cachedKeyPair.privateKey, data);           },           console.log.bind(console))     .then(function(signature) {               // Complete the Certification Request with |signature|.               // Send out the request to the CA, calling back               // onClientCertificateReceived.           },           console.log.bind(console)); }  function onClientCertificateReceived(userToken, certificate) {   chrome.enterprise.platformKeys.importCertificate(userToken.id, certificate); }  getUserToken(generateAndSign);

الأنواع

Algorithm

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

نوع المفتاح المطلوب إنشاؤه.

Enum

"RSA"

"ECDSA"

ChallengeKeyOptions

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

الخصائص

  • تحدّي

    ArrayBuffer

    تمثّل هذه السمة تحديًا تم إصداره من خلال Verified Access Web API.

  • registerKey

    RegisterKeyOptions اختيارية

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

  • نطاق

    المستوى

    مفتاح Enterprise الذي سيتم استخدامه في اختبار التحقّق

RegisterKeyOptions

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

الخصائص

  • خوارزمية

    الخوارزمية

    تحدّد هذه السمة الخوارزمية التي يجب أن يستخدمها المفتاح المسجَّل.

Scope

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

تحديد ما إذا كنت تريد استخدام "مفتاح مستخدم Enterprise" أو "مفتاح جهاز Enterprise"

Enum

"USER"

"MACHINE"

Token

الخصائص

  • id

    سلسلة

    يحدّد هذا Token بشكلٍ فريد.

    المعرّفان الثابتان هما "user" و"system"، ويشيران إلى الرمز المميز للأجهزة الخاص بالمستخدم على المنصة والرمز المميز للأجهزة على مستوى النظام، على التوالي. قد تعرض الدالة enterprise.platformKeys.getTokens أي رموز مميّزة أخرى (مع معرّفات أخرى).

  • softwareBackedSubtleCrypto

    SubtleCrypto

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

    تنفّذ واجهة SubtleCrypto في WebCrypto. تتم عمليات التشفير، بما في ذلك إنشاء المفاتيح، باستخدام البرامج. تتم حماية المفاتيح، وبالتالي تنفيذ خاصية عدم إمكانية الاستخراج، في البرامج، لذا تكون المفاتيح أقل حماية من المفاتيح المستنِدة إلى الجهاز.

    لا يمكن إنشاء سوى المفاتيح غير القابلة للاستخراج. أنواع المفاتيح المتوافقة هي RSASSA-PKCS1-V1_5 وRSA-OAEP (في الإصدار 135 من Chrome والإصدارات الأحدث) مع modulusLength حتى 2048. يمكن استخدام كل مفتاح RSASSA-PKCS1-V1_5 لتوقيع البيانات مرة واحدة على الأكثر، ما لم تتم إضافة الإضافة إلى القائمة المسموح بها من خلال سياسة KeyPermissions، وفي هذه الحالة يمكن استخدام المفتاح إلى أجل غير مسمى. تتوفّر مفاتيح RSA-OAEP منذ الإصدار 135 من Chrome، ويمكن أن تستخدمها الإضافات المدرَجة في القائمة المسموح بها من خلال السياسة نفسها لفك تشفير المفاتيح الأخرى.

    لا يمكن استخدام المفاتيح التي تم إنشاؤها على Token معيّن مع أي رموز مميّزة أخرى، كما لا يمكن استخدامها مع window.crypto.subtle. وبالمثل، لا يمكن استخدام عناصر Key التي تم إنشاؤها باستخدام window.crypto.subtle مع هذه الواجهة.

  • subtleCrypto

    SubtleCrypto

    تنفّذ واجهة SubtleCrypto في WebCrypto. تكون عمليات التشفير، بما في ذلك إنشاء المفاتيح، محمية بواسطة الأجهزة.

    لا يمكن إنشاء سوى المفاتيح غير القابلة للاستخراج. أنواع المفاتيح المتوافقة هي RSASSA-PKCS1-V1_5 وRSA-OAEP (في الإصدار 135 من Chrome والإصدارات الأحدث) مع modulusLength حتى 2048 وECDSA مع namedCurve P-256. يمكن استخدام كل مفتاح RSASSA-PKCS1-V1_5 وECDSA لتوقيع البيانات مرة واحدة على الأكثر، ما لم تتم إضافة الإضافة إلى القائمة المسموح بها من خلال سياسة KeyPermissions، وفي هذه الحالة يمكن استخدام المفتاح إلى أجل غير مسمى. تتوفّر مفاتيح RSA-OAEP منذ الإصدار 135 من Chrome، ويمكن أن تستخدمها الإضافات المدرَجة في القائمة المسموح بها من خلال السياسة نفسها لفك تشفير المفاتيح الأخرى.

    لا يمكن استخدام المفاتيح التي تم إنشاؤها على Token معيّن مع أي رموز مميّزة أخرى، كما لا يمكن استخدامها مع window.crypto.subtle. وبالمثل، لا يمكن استخدام عناصر Key التي تم إنشاؤها باستخدام window.crypto.subtle مع هذه الواجهة.

الطُرق

challengeKey()

Promise Chrome 110 والإصدارات الأحدث 
chrome.enterprise.platformKeys.challengeKey(
  options: ChallengeKeyOptions,
  callback?: function,
): Promise<ArrayBuffer>

تشبه الدالتَين challengeMachineKey وchallengeUserKey، ولكنها تسمح بتحديد خوارزمية مفتاح مسجّل. تحدّي "مفتاح الجهاز للمؤسسات" المحمي بواسطة الأجهزة وإصدار الردّ كجزء من بروتوكول إثبات صحة عن بُعد لا يمكن استخدامها إلا على ChromeOS وبالتزامن مع واجهة برمجة التطبيقات Verified Access Web API التي تطرح تحديات وتتحقّق من الردود.

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

هذه الوظيفة مقيّدة للغاية ولن تنجح إذا لم يكن الجهاز الحالي مُدارًا أو لم يكن المستخدم الحالي مُدارًا أو إذا لم يتم تفعيل هذه العملية بشكل صريح للمتصل من خلال سياسة الجهاز في المؤسسة. لا يوجد المفتاح الذي تم التحقّق منه في الرمز المميّز "system" أو "user"، ولا يمكن لأي واجهة برمجة تطبيقات أخرى الوصول إليه.

المعلمات

  • الخيارات

    ChallengeKeyOptions

    عنصر يحتوي على الحقول المحدّدة في ChallengeKeyOptions

  • callback

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

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

    (response: ArrayBuffer) => void

    • رد

      ArrayBuffer

      ردّ التحدي

المرتجعات

  • Promise<ArrayBuffer>

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

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

challengeMachineKey()

Promise الإصدار 50 من Chrome والإصدارات الأحدث تم إيقافها نهائيًا منذ الإصدار 110 من Chrome
chrome.enterprise.platformKeys.challengeMachineKey(
  challenge: ArrayBuffer,
  registerKey?: boolean,
  callback?: function,
): Promise<ArrayBuffer>

استخدِم challengeKey بدلاً من ذلك.

تحدّي "مفتاح الجهاز للمؤسسات" المحمي بواسطة الأجهزة وإصدار الردّ كجزء من بروتوكول إثبات صحة عن بُعد لا يمكن استخدامها إلا على ChromeOS وبالتزامن مع واجهة برمجة التطبيقات Verified Access Web API التي تطرح تحديات وتتحقّق من الردود. يشير التحقّق الناجح من خلال Verified Access Web API إلى ما يلي: * الجهاز الحالي هو جهاز ChromeOS صالح. * تتم إدارة الجهاز الحالي من خلال النطاق المحدّد أثناء عملية إثبات الملكية. * تتم إدارة المستخدم الذي سجّل الدخول حاليًا من خلال النطاق المحدّد أثناء عملية إثبات الملكية. * تتوافق حالة الجهاز الحالية مع سياسة الجهاز في المؤسسة. على سبيل المثال، قد تحدّد إحدى السياسات أنّه يجب ألا يكون الجهاز في وضع مطوّر البرامج. * أي هوية جهاز يتم إصدارها من خلال عملية التحقّق تكون مرتبطة بشكل وثيق بأجهزة الجهاز الحالي. هذه الوظيفة مقيّدة للغاية ولن تنجح إذا لم يكن الجهاز الحالي مُدارًا أو لم يكن المستخدم الحالي مُدارًا أو إذا لم يتم تفعيل هذه العملية بشكل صريح للمتصل من خلال سياسة الجهاز في المؤسسة. لا يتوفّر "مفتاح الجهاز الخاص بالمؤسسة" في الرمز المميّز "system" ولا يمكن الوصول إليه من خلال أي واجهة برمجة تطبيقات أخرى.

المعلمات

  • تحدّي

    ArrayBuffer

    تمثّل هذه السمة تحديًا تم إصداره من خلال Verified Access Web API.

  • registerKey

    boolean اختياري

    Chrome 59 والإصدارات الأحدث

    في حال ضبط هذا الخيار، يتم تسجيل "مفتاح الجهاز للمؤسسات" الحالي باستخدام الرمز المميّز "system" ويتم التخلي عن دور "مفتاح الجهاز للمؤسسات". ويمكن بعد ذلك ربط المفتاح بشهادة واستخدامه مثل أي مفتاح توقيع آخر. هذا المفتاح هو مفتاح RSA بحجم 2048 بت. ستؤدي عمليات الاستدعاء اللاحقة لهذه الدالة إلى إنشاء مفتاح Enterprise Machine Key جديد.

  • callback

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

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

    (response: ArrayBuffer) => void

    • رد

      ArrayBuffer

      ردّ التحدي

المرتجعات

  • Promise<ArrayBuffer>

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

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

challengeUserKey()

Promise الإصدار 50 من Chrome والإصدارات الأحدث تم إيقافها نهائيًا منذ الإصدار 110 من Chrome
chrome.enterprise.platformKeys.challengeUserKey(
  challenge: ArrayBuffer,
  registerKey: boolean,
  callback?: function,
): Promise<ArrayBuffer>

استخدِم challengeKey بدلاً من ذلك.

تحدّي "مفتاح مستخدم المؤسسة" المحمي بواسطة الجهاز وإصدار الرد كجزء من بروتوكول إثبات صحة عن بُعد لا يمكن استخدامها إلا على ChromeOS وبالتزامن مع واجهة برمجة التطبيقات Verified Access Web API التي تطرح تحديات وتتحقّق من الردود. يشير التحقّق الناجح من خلال Verified Access Web API إلى ما يلي: * الجهاز الحالي هو جهاز ChromeOS صالح. * تتم إدارة الجهاز الحالي من خلال النطاق المحدّد أثناء عملية إثبات الملكية. * تتم إدارة المستخدم الذي سجّل الدخول حاليًا من خلال النطاق المحدّد أثناء عملية إثبات الملكية. * تتوافق حالة الجهاز الحالية مع سياسة مستخدمي الإصدار الخاص بالمؤسسات. على سبيل المثال، قد تحدّد إحدى السياسات أنّه يجب ألا يكون الجهاز في وضع مطوّر البرامج. * المفتاح العام الذي يتم إصداره أثناء عملية التحقّق مرتبط بشكل وثيق بأجهزة الجهاز الحالي والمستخدم الحالي الذي سجّل الدخول. هذه الوظيفة مقيّدة بشدة ولن تنجح إذا لم يكن الجهاز الحالي مُدارًا أو لم يكن المستخدم الحالي مُدارًا أو إذا لم يتم تفعيل هذه العملية بشكل صريح للمتصل من خلال سياسة المستخدم في المؤسسة. لا يتوفّر "مفتاح مستخدم المؤسسة" في الرمز المميّز "user" ولا يمكن الوصول إليه من خلال أي واجهة برمجة تطبيقات أخرى.

المعلمات

  • تحدّي

    ArrayBuffer

    تمثّل هذه السمة تحديًا تم إصداره من خلال Verified Access Web API.

  • registerKey

    قيمة منطقية

    في حال ضبط هذا الخيار، يتم تسجيل "مفتاح مستخدم المؤسسة" الحالي باستخدام رمز "user" المميز ويتم التنازل عن دور "مفتاح مستخدم المؤسسة". ويمكن بعد ذلك ربط المفتاح بشهادة واستخدامه مثل أي مفتاح توقيع آخر. هذا المفتاح هو مفتاح RSA بحجم 2048 بت. ستؤدي المكالمات اللاحقة إلى هذه الدالة إلى إنشاء مفتاح مستخدم جديد في Enterprise.

  • callback

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

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

    (response: ArrayBuffer) => void

    • رد

      ArrayBuffer

      ردّ التحدي

المرتجعات

  • Promise<ArrayBuffer>

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

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

getCertificates()

الوعد 
chrome.enterprise.platformKeys.getCertificates(
  tokenId: string,
  callback?: function,
): Promise<ArrayBuffer[]>

تعرض هذه الطريقة قائمة بجميع شهادات العميل المتاحة من الرمز المميّز المحدّد. يمكن استخدامها للتحقّق من توفّر شهادات العميل التي يمكن استخدامها في مصادقة معيّنة ومن تاريخ انتهاء صلاحيتها.

المعلمات

  • tokenId

    سلسلة

    معرّف الرمز المميّز الذي تعرضه getTokens.

  • callback

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

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

    (certificates: ArrayBuffer[]) => void

    • الشهادات

      ArrayBuffer[]

      قائمة الشهادات، كل منها بترميز DER لشهادة X.509

المرتجعات

  • Promise<ArrayBuffer[]>

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

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

getTokens()

الوعد 
chrome.enterprise.platformKeys.getTokens(
  callback?: function,
): Promise<Token[]>

تعرض هذه الطريقة الرموز المميزة المتاحة. في جلسة مستخدم عادي، ستتضمّن القائمة دائمًا رمز المستخدم مع id "user". إذا كان الرمز المميز لوحدة النظام الأساسي الموثوقة (TPM) متاحًا على مستوى النظام، ستتضمّن القائمة التي يتم عرضها أيضًا الرمز المميز على مستوى النظام مع id "system". سيكون الرمز المميز على مستوى النظام هو نفسه لجميع الجلسات على هذا الجهاز (الجهاز بمعنى جهاز Chromebook مثلاً).

المعلمات

  • callback

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

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

    (tokens: Token[]) => void

    • الرموز المميزة

      Token[]

      قائمة الرموز المميزة المتاحة

المرتجعات

  • Promise<Token[]>

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

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

importCertificate()

الوعد 
chrome.enterprise.platformKeys.importCertificate(
  tokenId: string,
  certificate: ArrayBuffer,
  callback?: function,
): Promise<void>

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

المعلمات

  • tokenId

    سلسلة

    معرّف الرمز المميّز الذي تعرضه getTokens.

  • الشهادة

    ArrayBuffer

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

  • callback

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

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

    () => void

المرتجعات

  • Promise<void>

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

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

removeCertificate()

الوعد 
chrome.enterprise.platformKeys.removeCertificate(
  tokenId: string,
  certificate: ArrayBuffer,
  callback?: function,
): Promise<void>

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

المعلمات

  • tokenId

    سلسلة

    معرّف الرمز المميّز الذي تعرضه getTokens.

  • الشهادة

    ArrayBuffer

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

  • callback

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

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

    () => void

المرتجعات

  • Promise<void>

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

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