الوصف
استخدِم واجهة برمجة التطبيقات chrome.enterprise.platformKeys
لإنشاء مفاتيح وتثبيت شهادات لهذه المفاتيح. وستتم إدارة الشهادات من خلال النظام الأساسي، ويمكن استخدامها لمصادقة بروتوكول أمان طبقة النقل (TLS) أو الوصول إلى الشبكة أو من خلال إضافة أخرى من خلال chrome.platformKeys.
الأذونات
enterprise.platformKeys
مدى التوفّر
الاستخدام
إنّ الاستخدام النموذجي لواجهة برمجة التطبيقات هذه لتسجيل شهادة عميل يتبع الخطوات التالية:
يمكنك الحصول على جميع الرموز المميّزة المتاحة باستخدام 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
نوع المفتاح المراد إنشاؤه.
Enum
"شريك البيع بالتجزئة"
"ECDSA"
ChallengeKeyOptions
أماكن إقامة
-
تحدّي
مخزن المصفوفات
تحدٍ كما تنتجه واجهة برمجة التطبيقات لإمكانية الوصول المعتمد على الويب.
-
registerKey
RegisterKeyOptions اختيارية
في حال توفُّرها، يتم تسجيل المفتاح الذي تم إجراء تحدٍ فيه باستخدام الرمز المميّز المحدّد من
scope
. ويمكن بعد ذلك ربط المفتاح بشهادة واستخدامه، مثل أي مفتاح توقيع آخر. ستؤدي الطلبات اللاحقة لهذه الدالة إلى إنشاء مفتاح Enterprise جديد فيscope
المحدَّد. -
نطاق
مفتاح Enterprise الذي يجب تحديه.
RegisterKeyOptions
أماكن إقامة
-
خوارزمية
الخوارزمية التي يجب أن يستخدمها المفتاح المسجَّل.
Scope
تحديد ما إذا كنت تريد استخدام مفتاح مستخدم المؤسسة أو مفتاح جهاز المؤسسة
Enum
"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.enterprise.platformKeys.challengeKey(
options: ChallengeKeyOptions,
callback: function,
)
يشبه هذا المفتاح challengeMachineKey
وchallengeUserKey
، ولكنه يسمح بتحديد خوارزمية مفتاح مسجَّل. يحدّ من تشغيل مفتاح جهاز Enterprise مستند إلى الجهاز وينبعث منه استجابة كجزء من بروتوكول المصادقة عن بُعد. ولا يكون هذا الإجراء مفيدًا إلا على نظام التشغيل ChromeOS وواجهة برمجة تطبيقات الويب ذات الوصول المتحقَّق منه، والتي تعمل على إصدار تحديات والتحقّق من الاستجابات.
وتكون عملية إثبات الملكية الناجحة من خلال واجهة برمجة التطبيقات لإمكانية الوصول المعتمد على الويب إشارة قوية على أنّ الجهاز الحالي هو جهاز شرعي يعمل بنظام التشغيل Chrome، وأنّ الجهاز الحالي تتم إدارته من خلال النطاق المحدّد أثناء إثبات الملكية، كما تتم إدارة المستخدم الحالي الذي سجّل الدخول من خلال النطاق المحدّد أثناء إثبات الملكية، وتمتثل حالة الجهاز الحالية لسياسة أجهزة المؤسسة. على سبيل المثال، قد تحدد السياسة أنه يجب ألا يكون الجهاز في وضع مطور البرامج. وترتبط بالجهاز الحالي بإحكام عن هوية أي جهاز ينبعث من عملية التحقّق. في حال تحديد نطاق "user"
، يتم أيضًا ربط الهوية بسرعة للمستخدم الحالي الذي سجَّل الدخول.
هذه الوظيفة محظورة للغاية ولن تنجح إذا لم يكن الجهاز الحالي مُدارًا أو إذا لم يكن المستخدم الحالي مُدارًا أو إذا لم يتم تفعيل هذه العملية صراحةً للمتصل من خلال سياسة جهاز المؤسسة. لا يتوفّر مفتاح الاختبار في الرمز المميّز "system"
أو "user"
ولا يمكن الوصول إليه من خلال أي واجهة برمجة تطبيقات أخرى.
المعلمات
-
الخيارات
عنصر يحتوي على الحقول المحدّدة في
ChallengeKeyOptions
-
رد الاتصال
دالة
تظهر المَعلمة
callback
على النحو التالي:(response: ArrayBuffer) => void
-
رد
مخزن المصفوفات
الاستجابة للتحدي.
-
challengeMachineKey()
chrome.enterprise.platformKeys.challengeMachineKey(
challenge: ArrayBuffer,
registerKey?: boolean,
callback: function,
)
يمكنك استخدام challengeKey
بدلاً من ذلك.
يحدّ من تشغيل مفتاح جهاز Enterprise مستند إلى الجهاز وينبعث منه استجابة كجزء من بروتوكول المصادقة عن بُعد. ولا يكون هذا الإجراء مفيدًا إلا على نظام التشغيل ChromeOS وواجهة برمجة تطبيقات الويب ذات الوصول المتحقَّق منه، والتي تعمل على إصدار تحديات والتحقّق من الاستجابات. وتمثّل عملية إثبات الملكية الناجحة من خلال واجهة برمجة التطبيقات لإمكانية الوصول المعتمد على الويب إشارة قوية لجميع ما يلي: * الجهاز الحالي جهاز شرعي يعمل بنظام التشغيل ChromeOS. * تتم إدارة الجهاز الحالي من خلال النطاق الذي تم تحديده أثناء إثبات الملكية. * تتم إدارة المستخدم الحالي الذي سجّل الدخول من خلال النطاق المحدد أثناء إثبات الملكية. * تتوافق حالة الجهاز الحالية مع سياسة أجهزة المؤسسة. على سبيل المثال، قد تحدد السياسة أنه يجب ألا يكون الجهاز في وضع مطور البرامج. * ترتبط أي هوية جهاز صادرة من خلال عملية إثبات الهوية بأجهزة الجهاز الحالي بإحكام. هذه الوظيفة محظورة للغاية ولن تنجح إذا لم يكن الجهاز الحالي مُدارًا أو إذا لم يكن المستخدم الحالي مُدارًا أو إذا لم يتم تفعيل هذه العملية صراحةً للمتصل من خلال سياسة جهاز المؤسسة. لا يتوفّر مفتاح جهاز Enterprise في الرمز المميّز "system"
ولا يمكن الوصول إليه من خلال أي واجهة برمجة تطبيقات أخرى.
المعلمات
-
تحدّي
مخزن المصفوفات
تحدٍ كما تنتجه واجهة برمجة التطبيقات لإمكانية الوصول المعتمد على الويب.
-
registerKey
قيمة منطقية اختيارية
الإصدار 59 من Chrome أو الإصدارات الأحدثوفي حال ضبط مفتاح جهاز Enterprise الحالي، يتم تسجيله بالرمز المميّز
"system"
ويتنازل عن دور مفتاح جهاز Enterprise. ويمكن بعد ذلك ربط المفتاح بشهادة واستخدامه، مثل أي مفتاح توقيع آخر. هذا المفتاح هو RSA بحجم 2048 بت. وستؤدي الطلبات اللاحقة لهذه الدالة إلى إنشاء مفتاح جهاز Enterprise جديد. -
رد الاتصال
دالة
تظهر المَعلمة
callback
على النحو التالي:(response: ArrayBuffer) => void
-
رد
مخزن المصفوفات
الاستجابة للتحدي.
-
challengeUserKey()
chrome.enterprise.platformKeys.challengeUserKey(
challenge: ArrayBuffer,
registerKey: boolean,
callback: function,
)
يمكنك استخدام challengeKey
بدلاً من ذلك.
يتحدى مفتاح مستخدم Enterprise مدعومًا آليًا وينبعث من الاستجابة كجزء من بروتوكول المصادقة عن بُعد. ولا يكون هذا الإجراء مفيدًا إلا على نظام التشغيل ChromeOS وواجهة برمجة تطبيقات الويب ذات الوصول المتحقَّق منه، والتي تعمل على إصدار تحديات والتحقّق من الاستجابات. وتمثّل عملية إثبات الملكية الناجحة من خلال واجهة برمجة التطبيقات لإمكانية الوصول المعتمد على الويب إشارة قوية لجميع ما يلي: * الجهاز الحالي جهاز شرعي يعمل بنظام التشغيل ChromeOS. * تتم إدارة الجهاز الحالي من خلال النطاق الذي تم تحديده أثناء إثبات الملكية. * تتم إدارة المستخدم الحالي الذي سجّل الدخول من خلال النطاق المحدد أثناء إثبات الملكية. * تلتزم حالة الجهاز الحالية بسياسة مستخدم المؤسسة. على سبيل المثال، قد تحدد السياسة أنه يجب ألا يكون الجهاز في وضع مطور البرامج. * يرتبط المفتاح العام المنبعث من عملية إثبات الملكية ارتباطًا وثيقًا بأجهزة الجهاز الحالي وبالمستخدم الحالي الذي سجّل الدخول. هذه الوظيفة محظورة للغاية ولن تنجح إذا لم يكن الجهاز الحالي مُدارًا أو إذا لم يكن المستخدم الحالي مُدارًا أو إذا لم يتم تفعيل هذه العملية صراحةً للمتصل من خلال سياسة مستخدم المؤسسة. لا يتوفّر مفتاح مستخدم المؤسسة في الرمز المميّز "user"
ولا يمكن الوصول إليه من خلال أي واجهة برمجة تطبيقات أخرى.
المعلمات
-
تحدّي
مخزن المصفوفات
تحدٍ كما تنتجه واجهة برمجة التطبيقات لإمكانية الوصول المعتمد على الويب.
-
registerKey
منطقي
وفي حال ضبط مفتاح مستخدم Enterprise الحالي، يتم تسجيله بالرمز المميّز
"user"
ويتنازل عن دور مفتاح مستخدم المؤسسة. ويمكن بعد ذلك ربط المفتاح بشهادة واستخدامه، مثل أي مفتاح توقيع آخر. هذا المفتاح هو RSA بحجم 2048 بت. ستؤدي الاستدعاءات اللاحقة لهذه الدالة إلى إنشاء مفتاح مستخدم Enterprise جديد. -
رد الاتصال
دالة
تظهر المَعلمة
callback
على النحو التالي:(response: ArrayBuffer) => void
-
رد
مخزن المصفوفات
الاستجابة للتحدي.
-
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
-
الشهادة
مخزن المصفوفات
ترميز DER لشهادة X.509
-
رد الاتصال
الدالة اختيارية
تظهر المَعلمة
callback
على النحو التالي:() => void
removeCertificate()
chrome.enterprise.platformKeys.removeCertificate(
tokenId: string,
certificate: ArrayBuffer,
callback?: function,
)
ستتم إزالة certificate
من الرمز المميّز إذا كان متوفّرًا. يجب استخدام هذا الإجراء لإزالة الشهادات القديمة كي لا يتم أخذها في الاعتبار أثناء المصادقة ولا تؤدي إلى فوضى في خيار الشهادة. يجب استخدامها لتوفير مساحة تخزين في مخزن الشهادات.
المعلمات
-
tokenId
سلسلة
معرّف الرمز المميّز الذي يعرضه
getTokens
-
الشهادة
مخزن المصفوفات
ترميز DER لشهادة X.509
-
رد الاتصال
الدالة اختيارية
تظهر المَعلمة
callback
على النحو التالي:() => void