chrome.enterprise.platformKeys

الوصف

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

الأذونات

enterprise.platformKeys

مدى التوفّر

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

الاستخدام

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

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

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

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

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

  • أنشئ توقيع بيانات طلب الاعتماد باستخدام طريقة sign Token (المحدّدة في 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 والإصدارات الأحدث

نوع المفتاح الذي تريد إنشاؤه

تعداد

"RSA"

"ECDSA"

ChallengeKeyOptions

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

أماكن إقامة

  • تحدّي

    ArrayBuffer

    تحدّي يُرسله Verified Access Web API

  • registerKey

    ‫RegisterKeyOptions اختياري

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

  • نطاق

    المستوى

    مفتاح اختبار التحقق المطلوب إعادة فحصه

RegisterKeyOptions

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

أماكن إقامة

  • خوارزمية

    الخوارزمية

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

Scope

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

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

تعداد

"USER"

"MACHINE"

Token

أماكن إقامة

  • id

    سلسلة

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

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

  • softwareBackedSubtleCrypto

    SubtleCrypto

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

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

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

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

  • subtleCrypto

    SubtleCrypto

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

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

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

الطُرق

challengeKey()

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

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

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

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

المعلمات

  • الخيارات

    ChallengeKeyOptions

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

  • ردّ الاتصال

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

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

    (response: ArrayBuffer) => void

    • رد

      ArrayBuffer

      ردّ على التحدي

المرتجعات

  • Promise<ArrayBuffer>

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

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

challengeMachineKey()

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

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

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

المعلمات

  • تحدّي

    ArrayBuffer

    تحدّي يُرسله Verified Access Web API

  • registerKey

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

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

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

  • ردّ الاتصال

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

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

    (response: ArrayBuffer) => void

    • رد

      ArrayBuffer

      ردّ على التحدي

المرتجعات

  • Promise<ArrayBuffer>

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

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

challengeUserKey()

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

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

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

المعلمات

  • تحدّي

    ArrayBuffer

    تحدّي يُرسله Verified Access Web API

  • registerKey

    قيمة منطقية

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

  • ردّ الاتصال

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

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

    (response: ArrayBuffer) => void

    • رد

      ArrayBuffer

      ردّ على التحدي

المرتجعات

  • Promise<ArrayBuffer>

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

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

getCertificates()

الوعد 
chrome.enterprise.platformKeys.getCertificates(
  tokenId: string,
  callback?: function,
)

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

المعلمات

  • tokenId

    سلسلة

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

  • ردّ الاتصال

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

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

    (certificates: ArrayBuffer[]) => void

    • الشهادات

      ArrayBuffer[]

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

المرتجعات

  • Promise<ArrayBuffer[]>

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

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

getTokens()

الوعد 
chrome.enterprise.platformKeys.getTokens(
  callback?: function,
)

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

المعلمات

  • ردّ الاتصال

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

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

    (tokens: Token[]) => void

المرتجعات

  • Promise<Token[]>

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

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

importCertificate()

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

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

المعلمات

  • tokenId

    سلسلة

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

  • الشهادة

    ArrayBuffer

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

  • ردّ الاتصال

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

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

    () => void

المرتجعات

  • Promise<void>

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

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

removeCertificate()

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

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

المعلمات

  • tokenId

    سلسلة

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

  • الشهادة

    ArrayBuffer

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

  • ردّ الاتصال

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

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

    () => void

المرتجعات

  • Promise<void>

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

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