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

"ECDSA"

ChallengeKeyOptions

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

أماكن إقامة

  • تحدّي

    ArrayBuffer

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

  • registerKey

    RegisterKeyOptions اختيارية

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

  • نطاق

    المستوى

    مفتاح Enterprise الذي يجب تحديه.

RegisterKeyOptions

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

أماكن إقامة

  • خوارزمية

    الخوارزمية

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

Scope

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

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

التعداد

"USER"

Token

أماكن إقامة

  • id

    سلسلة

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

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

  • softwareBackedSubtleCrypto

    SubtleCrypto

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

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

    لا يمكن إنشاء مفاتيح RSASSA-PKCS1-V1_5 غير القابلة للاستخراج التي تبلغ modulusLength ما يصل إلى 2048. يمكن استخدام كل مفتاح لتوقيع البيانات مرة واحدة فقط.

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

  • subtleCrypto

    SubtleCrypto

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

    لا يمكن إنشاء سوى مفاتيح RSASSA-PKCS1-V1_5 غير القابلة للاستخراج التي تعمل بـ modulusLength حتى 2048 وECDSA مع namedCurve P-256. يمكن استخدام كل مفتاح لتوقيع البيانات مرة واحدة فقط.

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

الطُرق

challengeKey()

وعود الإصدار 110 من Chrome والإصدارات الأحدث 
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>

    في انتظار المراجعة

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

challengeMachineKey()

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

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

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

المعلمات

  • تحدّي

    ArrayBuffer

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

  • registerKey

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

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

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

  • رد الاتصال

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

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

    (response: ArrayBuffer) => void

    • رد

      ArrayBuffer

      الاستجابة للتحدي.

المرتجعات

  • Promise<ArrayBuffer>

    في انتظار المراجعة

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

challengeUserKey()

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

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

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

المعلمات

  • تحدّي

    ArrayBuffer

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

  • registerKey

    منطقي

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

  • رد الاتصال

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

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

    (response: ArrayBuffer) => void

    • رد

      ArrayBuffer

      الاستجابة للتحدي.

المرتجعات

  • Promise<ArrayBuffer>

    في انتظار المراجعة

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

getCertificates()

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

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

المعلمات

  • tokenId

    سلسلة

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

  • ردّ الاتصال

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

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

    (certificates: ArrayBuffer[]) => void

    • الشهادات

      ArrayBuffer[]

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

المرتجعات

  • Promise<ArrayBuffer[]>

    في انتظار المراجعة

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

getTokens()

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

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

المعلمات

  • رد الاتصال

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

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

    (tokens: Token[]) => void

المرتجعات

  • الوعد<Token[]>

    في انتظار المراجعة

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

importCertificate()

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

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

المعلمات

  • tokenId

    سلسلة

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

  • الشهادة

    ArrayBuffer

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

  • رد الاتصال

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

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

    () => void

المرتجعات

  • Promise<void>

    في انتظار المراجعة

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

removeCertificate()

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

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

المعلمات

  • tokenId

    سلسلة

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

  • الشهادة

    ArrayBuffer

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

  • رد الاتصال

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

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

    () => void

المرتجعات

  • Promise<void>

    في انتظار المراجعة

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