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

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

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

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

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

التعداد

"ECDSA"

ChallengeKeyOptions

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

أماكن إقامة

  • تحدّي

    ArrayBuffer

    تحدٍ كما تنتجه واجهة برمجة التطبيقات لإمكانية الوصول المعتمد على الويب.

  • registerKey

    RegisterKeyOptions اختيارية

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

  • نطاق

    المستوى

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

RegisterKeyOptions

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

أماكن إقامة

  • خوارزمية

    الخوارزمية

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

Scope

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

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

التعداد

"USER"

Token

أماكن إقامة

  • id

    سلسلة

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

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

  • softwareBackedSubtleCrypto

    SubtleCrypto

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

    تنفيذ واجهة 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()

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

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

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

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

المعلمات

  • الخيارات

    ChallengeKeyOptions

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

  • رد الاتصال

    الوظيفة

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

    (response: ArrayBuffer) => void

    • رد

      ArrayBuffer

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

challengeMachineKey()

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

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

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

المعلمات

  • تحدّي

    ArrayBuffer

    تحدٍ كما تنتجه واجهة برمجة التطبيقات لإمكانية الوصول المعتمد على الويب.

  • registerKey

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

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

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

  • رد الاتصال

    الوظيفة

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

    (response: ArrayBuffer) => void

    • رد

      ArrayBuffer

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

challengeUserKey()

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

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

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

المعلمات

  • تحدّي

    ArrayBuffer

    تحدٍ كما تنتجه واجهة برمجة التطبيقات لإمكانية الوصول المعتمد على الويب.

  • registerKey

    boolean

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

  • رد الاتصال

    الوظيفة

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

    (response: ArrayBuffer) => void

    • رد

      ArrayBuffer

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

getCertificates()

chrome.enterprise.platformKeys.getCertificates(
  tokenId: string,
  callback: function,
)

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

المعلمات

  • tokenId

    سلسلة

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

  • رد الاتصال

    الوظيفة

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

    (certificates: ArrayBuffer[]) => void

    • الشهادات

      ArrayBuffer[]

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

getTokens()

chrome.enterprise.platformKeys.getTokens(
  callback: function,
)

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

المعلمات

  • رد الاتصال

    الوظيفة

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

    (tokens: Token[]) => void

    • رموز مميزة

      الرمز المميّز[]

      تمثّل هذه السمة قائمة الرموز المميّزة المتوفّرة.

importCertificate()

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

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

المعلمات

  • tokenId

    سلسلة

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

  • الشهادة

    ArrayBuffer

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

  • رد الاتصال

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

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

    () => void

removeCertificate()

chrome.enterprise.platformKeys.removeCertificate(
  tokenId: string,
  certificate: ArrayBuffer,
  callback?: function,
)

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

المعلمات

  • tokenId

    سلسلة

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

  • الشهادة

    ArrayBuffer

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

  • رد الاتصال

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

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

    () => void