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

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

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

التعداد

ChallengeKeyOptions

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

أماكن إقامة

  • تحدّي

    ArrayBuffer

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

  • registerKey

    RegisterKeyOptions اختيارية

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

  • نطاق

    المستوى

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

RegisterKeyOptions

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

أماكن إقامة

  • خوارزمية

    الخوارزمية

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

Scope

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

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

التعداد

"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 وجنبًا إلى جنب مع واجهة برمجة التطبيقات Verified Access Web API التي تُصدر التحديات وتُحقّق من الردود.

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

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

المعلمات

  • الخيارات

    ChallengeKeyOptions

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

  • رد الاتصال

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

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

    (response: ArrayBuffer) => void

    • رد

      ArrayBuffer

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

المرتجعات

  • Promise&lt;ArrayBuffer&gt;

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

    تكون الوعود متاحة في الإصدار 3 من Manifest والإصدارات الأحدث، ولكن يتم توفير طلبات الاستدعاء من أجل التوافق مع الإصدارات القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. يتم حلّ الوعد بالنوع نفسه الذي يتم تمريره إلى الدالة المُعاد الاتصال بها.

challengeMachineKey()

وعود الإصدار 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

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

  • registerKey

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

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

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

  • ردّ الاتصال

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

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

    (response: ArrayBuffer) => void

    • رد

      ArrayBuffer

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

المرتجعات

  • Promise&lt;ArrayBuffer&gt;

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

    تكون الوعود متاحة في الإصدار 3 من Manifest والإصدارات الأحدث، ولكن يتم توفير طلبات الاستدعاء من أجل التوافق مع الإصدارات القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. يتم حلّ الوعد بالنوع نفسه الذي يتم تمريره إلى الدالة المُعاد الاتصال بها.

challengeUserKey()

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

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

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

المعلمات

  • تحدّي

    ArrayBuffer

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

  • registerKey

    منطقي

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

  • ردّ الاتصال

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

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

    (response: ArrayBuffer) => void

    • رد

      ArrayBuffer

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

المرتجعات

  • Promise&lt;ArrayBuffer&gt;

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

    تكون الوعود متاحة في الإصدار 3 من Manifest والإصدارات الأحدث، ولكن يتم توفير طلبات الاستدعاء من أجل التوافق مع الإصدارات القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. يتم حلّ الوعد بالنوع نفسه الذي يتم تمريره إلى الدالة المُعاد الاتصال بها.

getCertificates()

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

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

المعلمات

  • tokenId

    سلسلة

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

  • ردّ الاتصال

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

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

    (certificates: ArrayBuffer[]) => void

    • الشهادات

      ArrayBuffer[]

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

المرتجعات

  • Promise&lt;ArrayBuffer[]&gt;

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

    تكون الوعود متاحة في الإصدار 3 من Manifest والإصدارات الأحدث، ولكن يتم توفير طلبات الاستدعاء من أجل التوافق مع الإصدارات القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. يتم حلّ الوعد بالنوع نفسه الذي يتم تمريره إلى الدالة المُعاد الاتصال بها.

getTokens()

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

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

المعلمات

  • رد الاتصال

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

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

    (tokens: Token[]) => void

المرتجعات

  • الوعد<Token[]>

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

    تكون الوعود متاحة في الإصدار 3 من Manifest والإصدارات الأحدث، ولكن يتم توفير طلبات الاستدعاء من أجل التوافق مع الإصدارات القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. يتم حلّ الوعد بالنوع نفسه الذي يتم تمريره إلى الدالة المُعاد الاتصال بها.

importCertificate()

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

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

المعلمات

  • tokenId

    سلسلة

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

  • الشهادة

    ArrayBuffer

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

  • ردّ الاتصال

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

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

    () => void

المرتجعات

  • Promise<void>

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

    تكون الوعود متاحة في الإصدار 3 من Manifest والإصدارات الأحدث، ولكن يتم توفير طلبات الاستدعاء من أجل التوافق مع الإصدارات القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. يتم حلّ الوعد بالنوع نفسه الذي يتم تمريره إلى الدالة المُعاد الاتصال بها.

removeCertificate()

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

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

المعلمات

  • tokenId

    سلسلة

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

  • الشهادة

    ArrayBuffer

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

  • ردّ الاتصال

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

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

    () => void

المرتجعات

  • Promise<void>

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

    تكون الوعود متاحة في الإصدار 3 من Manifest والإصدارات الأحدث، ولكن يتم توفير طلبات الاستدعاء من أجل التوافق مع الإصدارات القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. يتم حلّ الوعد بالنوع نفسه الذي يتم تمريره إلى الدالة المُعاد الاتصال بها.