browser.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()`[3]

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

function getUserToken(callback) {
  browser.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) {
  browser.enterprise.platformKeys.importCertificate(userToken.id, certificate);
}

getUserToken(generateAndSign);

الأنواع

Algorithm

الإصدار 110 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

Enum

"RSA"

"ECDSA"

ChallengeKeyOptions

الإصدار 110 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

الخصائص

  • تحدّي

    ArrayBuffer

    تمثّل هذه السمة طلبًا كما تم إصداره من خلال واجهة برمجة التطبيقات Verified Access Web API.

  • registerKey

    RegisterKeyOptions اختياري

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

  • نطاق

    المستوى

    مفتاح Enterprise الذي سيتم التحقّق منه

RegisterKeyOptions

الإصدار 110 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

الخصائص

  • خوارزمية

    الخوارزمية

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

Scope

الإصدار 110 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

ما إذا كنت تريد استخدام مفتاح مستخدِم الإصدار الخاص بالمؤسسات أو مفتاح جهاز Enterprise.

Enum

"USER"

"MACHINE"

Token

الخصائص

  • id

    سلسلة

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

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

  • softwareBackedSubtleCrypto

    SubtleCrypto

    الإصدار 97 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

    يمكن إنشاء مفاتيح غير قابلة للاستخراج فقط. نوع المفتاح الوحيد المتوافق هو RSASSA-PKCS1-V1_5 مع modulusLength حتى 2048. يمكن استخدام كل مفتاح لتوقيع البيانات مرة واحدة على الأكثر، ما لم تتم إضافة الإضافة إلى القائمة المسموح بها من خلال سياسة KeyPermissions، وفي هذه الحالة يمكن استخدام المفتاح إلى أجل غير مسمى.

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

  • subtleCrypto

    SubtleCrypto

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

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

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

الطُرق

challengeKey()

الإصدار 110 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome 
browser.enterprise.platformKeys.challengeKey(
  options: ChallengeKeyOptions,
): Promise<ArrayBuffer>

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

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

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

المعلمات

المرتجعات

  • Promise<ArrayBuffer>

    الإصدار 131 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

    تعرض هذه الطريقة كائن Promise يتم حله من خلال استجابة التحدي.

challengeMachineKey()

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

يمكنك استخدام challengeKey كبديل.

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

المعلمات

  • تحدّي

    ArrayBuffer

    تمثّل هذه السمة طلبًا كما تم إصداره من خلال واجهة برمجة التطبيقات Verified Access Web API.

  • registerKey

    قيمة منطقية اختيارية

    الإصدار 59 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

المرتجعات

  • Promise<ArrayBuffer>

    الإصدار 131 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

    تعرض هذه الطريقة كائن Promise يتم حله من خلال استجابة التحدي.

challengeUserKey()

الإصدار 50 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome متوقّفة نهائيًا منذ الإصدار 110 من Chrome
browser.enterprise.platformKeys.challengeUserKey(
  challenge: ArrayBuffer,
  registerKey: boolean,
): Promise<ArrayBuffer>

يمكنك استخدام challengeKey كبديل.

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

المعلمات

  • تحدّي

    ArrayBuffer

    تمثّل هذه السمة طلبًا كما تم إصداره من خلال واجهة برمجة التطبيقات Verified Access Web API.

  • registerKey

    قيمة منطقية

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

المرتجعات

  • Promise<ArrayBuffer>

    الإصدار 131 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

    تعرض هذه الطريقة كائن Promise يتم حله من خلال استجابة التحدي.

getCertificates()

browser.enterprise.platformKeys.getCertificates(
  tokenId: string,
): Promise<ArrayBuffer[]>

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

المعلمات

  • tokenId

    سلسلة

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

المرتجعات

  • وعد<ArrayBuffer[]>

    الإصدار 131 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

    تعرض هذه الطريقة كائن Promise يتم حله باستخدام قائمة الشهادات المتاحة.

getTokens()

browser.enterprise.platformKeys.getTokens(): Promise<Token[]>

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

المرتجعات

  • Promise<Token[]>

    الإصدار 131 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

    يتم استدعاؤها من خلال "getTokens" مع قائمة الرموز المميّزة المتاحة.

importCertificate()

browser.enterprise.platformKeys.importCertificate(
  tokenId: string,
  certificate: ArrayBuffer,
): Promise<void>

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

المعلمات

  • tokenId

    سلسلة

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

  • الشهادة

    ArrayBuffer

    تمثّل هذه السمة ترميز DER لشهادة معيار X.509.

المرتجعات

  • وعد<فراغ>

    الإصدار 131 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

removeCertificate()

browser.enterprise.platformKeys.removeCertificate(
  tokenId: string,
  certificate: ArrayBuffer,
): Promise<void>

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

المعلمات

  • tokenId

    سلسلة

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

  • الشهادة

    ArrayBuffer

    تمثّل هذه السمة ترميز DER لشهادة معيار X.509.

المرتجعات

  • وعد<فراغ>

    الإصدار 131 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

    تعرض هذه الدالة Promise يتم حلّه عند انتهاء هذه العملية.