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 والإصدارات الأحدث

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

التعداد

"RSA"

"ECDSA"

ChallengeKeyOptions

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

أماكن إقامة

  • تحدّي

    ArrayBuffer

    تمثّل هذه السمة أحد التحديات الناتجة عن واجهة برمجة تطبيقات الويب لميزة "الوصول المتحقَّق منه".

  • registerKey

    RegisterKeyOptions اختيارية

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

  • نطاق

    المستوى

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

RegisterKeyOptions

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

أماكن إقامة

  • خوارزمية

    الخوارزمية

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

Scope

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

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

التعداد

"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()

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

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

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

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

المَعلمات

  • الخيارات

    ChallengeKeyOptions

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

  • معاودة الاتصال

    الوظيفة

    تبدو معلَمة callback على النحو التالي: 

    (response: ArrayBuffer)=>void

    • رد

      ArrayBuffer

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

challengeMachineKey()

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

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

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

المَعلمات

  • تحدّي

    ArrayBuffer

    تمثّل هذه السمة أحد التحديات الناتجة عن واجهة برمجة تطبيقات الويب لميزة "الوصول المتحقَّق منه".

  • registerKey

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

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

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

  • معاودة الاتصال

    الوظيفة

    تبدو معلَمة callback على النحو التالي: 

    (response: ArrayBuffer)=>void

    • رد

      ArrayBuffer

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

challengeUserKey()

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

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

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

المَعلمات

  • تحدّي

    ArrayBuffer

    تمثّل هذه السمة أحد التحديات الناتجة عن واجهة برمجة تطبيقات الويب لميزة "الوصول المتحقَّق منه".

  • registerKey

    boolean

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

  • معاودة الاتصال

    الوظيفة

    تبدو معلَمة 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". في حال توفّر رمز مميَّز لوحدة النظام الأساسي الموثوق به على مستوى النظام، ستحتوي القائمة المعروضة أيضًا على الرمز المميّز على مستوى النظام مع 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