الوصف
استخدِم واجهة برمجة التطبيقات chrome.enterprise.platformKeys
لإنشاء مفاتيح وتثبيت شهادات لهذه المفاتيح. ستدير المنصة الشهادات ويمكن استخدامها لمصادقة بروتوكول أمان طبقة النقل (TLS) أو الوصول إلى الشبكة أو من خلال إضافة أخرى من خلال chrome.platformKeys.
الأذونات
enterprise.platformKeys
مدى التوفّر
المفاهيم وطريقة الاستخدام
في ما يلي الخطوات المعتادة لاستخدام واجهة برمجة التطبيقات هذه لتسجيل شهادة عميل:
يمكنك الحصول على جميع الرموز المتاحة باستخدام
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
نوع المفتاح الذي تريد إنشاؤه
Enum
"RSA"
"ECDSA"
ChallengeKeyOptions
أماكن إقامة
-
تحدّي
ArrayBuffer
تحدّي يُرسله Verified Access Web API
-
registerKey
RegisterKeyOptions اختياري
في حال توفّر مفتاح التحدّي، يتم تسجيله باستخدام رمز
scope
المحدّد. ويمكن بعد ذلك ربط المفتاح بشهادة واستخدامه مثل أي مفتاح توقيع آخر. ستؤدي المكالمات اللاحقة إلى هذه الدالة إلى إنشاء مفتاح Enterprise جديد فيscope
المحدّد. -
نطاق
مفتاح اختبار التحقق المطلوب إعادة فحصه
RegisterKeyOptions
أماكن إقامة
-
خوارزمية
الخوارزمية التي يجب أن يستخدمها المفتاح المسجَّل
Scope
ما إذا كنت تريد استخدام مفتاح المستخدم في Enterprise أو مفتاح الجهاز في Enterprise
Enum
"USER"
"MACHINE"
Token
أماكن إقامة
-
id
سلسلة
يحدِّد هذا الحقل
Token
بشكلٍ فريد.المعرّفات الثابتة هي
"user"
و"system"
، وتشير إلى الرمز المميّز الخاص بالمستخدم على المنصة والرمز المميّز للأجهزة على مستوى النظام، على التوالي. قد يعرضenterprise.platformKeys.getTokens
أي رموز مميّزة أخرى (مع معرّفات أخرى). -
softwareBackedSubtleCrypto
SubtleCrypto
Chrome 97 والإصدارات الأحدثتُنفِّذ واجهة SubtleCrypto في WebCrypto. يتم تنفيذ عمليات التشفير، بما في ذلك إنشاء المفاتيح، باستخدام برامج. تتم حماية المفاتيح، وبالتالي تنفيذ السمة غير القابلة للاستخراج، في البرنامج، لذا تكون المفاتيح أقل حماية من المفاتيح المستندة إلى الأجهزة.
لا يمكن إنشاء سوى مفاتيح غير قابلة للاستخراج. أنواع المفاتيح المتوافقة هي RSASSA-PKCS1-V1_5 وRSA-OAEP مع
modulusLength
حتى 2048. يمكن استخدام كل مفتاح RSASSA-PKCS1-V1_5 لتوقيع البيانات مرة واحدة على الأكثر، ما لم تكن الإضافة مُدرَجة في القائمة المسموح بها من خلال سياسة KeyPermissions، وفي هذه الحالة يمكن استخدام المفتاح إلى أجل غير مسمى. يمكن استخدام مفاتيح RSA-OAEP من خلال الإضافات المدرَجة في القائمة المسموح بها في السياسة نفسها لفك تشفير مفاتيح أخرى.لا يمكن استخدام المفاتيح التي تم إنشاؤها على
Token
مع أي رموز أخرى، ولا يمكن استخدامها معwindow.crypto.subtle
. وبالمثل، لا يمكن استخدام عناصرKey
التي تم إنشاؤها باستخدامwindow.crypto.subtle
مع هذه الواجهة. -
subtleCrypto
SubtleCrypto
تُنفِّذ واجهة SubtleCrypto في WebCrypto. تستند عمليات التشفير، بما في ذلك إنشاء المفاتيح، إلى الأجهزة.
لا يمكن إنشاء سوى مفاتيح غير قابلة للاستخراج. أنواع المفاتيح المتوافقة هي RSASSA-PKCS1-V1_5 وRSA-OAEP مع
modulusLength
حتى 2048 وECDSA معnamedCurve
P-256. يمكن استخدام كل مفتاح من مفاتيح RSASSA-PKCS1-V1_5 وECDSA لتوقيع البيانات مرة واحدة على الأكثر، ما لم تكن الإضافة مُدرَجة في القائمة المسموح بها من خلال سياسة KeyPermissions، وفي هذه الحالة يمكن استخدام المفتاح إلى أجل غير مسمى. يمكن استخدام مفاتيح RSA-OAEP من خلال الإضافات المدرَجة في القائمة المسموح بها في السياسة نفسها لفك تشفير مفاتيح أخرى.لا يمكن استخدام المفاتيح التي تم إنشاؤها على
Token
مع أي رموز أخرى، ولا يمكن استخدامها معwindow.crypto.subtle
. وبالمثل، لا يمكن استخدام عناصرKey
التي تم إنشاؤها باستخدامwindow.crypto.subtle
مع هذه الواجهة.
الطُرق
challengeKey()
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
-
ردّ الاتصال
الدالة اختيارية
تظهر المَعلمة
callback
على النحو التالي:(response: ArrayBuffer) => void
-
رد
ArrayBuffer
ردّ على التحدي
-
المرتجعات
-
Promise<ArrayBuffer>
Chrome 131 والإصدارات الأحدثتتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير طلبات الاستدعاء لأجل التوافق مع الإصدارات القديمة. ولا يمكنك استخدام كليهما في طلب الدالة نفسه. يتم حلّ الوعد بالنوع نفسه الذي يتم تمريره إلى دالة الاستدعاء.
challengeMachineKey()
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
تحدّي يُرسله Verified Access Web API
-
registerKey
منطقي اختياري
Chrome 59 والإصدارات الأحدثفي حال ضبطه، يتم تسجيل مفتاح الجهاز الحالي للمؤسسات باستخدام الرمز المميّز
"system"
ويتخلّى عن دور مفتاح الجهاز للمؤسسات. ويمكن بعد ذلك ربط المفتاح بشهادة واستخدامه مثل أي مفتاح توقيع آخر. هذا المفتاح هو مفتاح RSA بسعة 2048 بت. ستؤدي المكالمات اللاحقة إلى هذه الدالة إلى إنشاء مفتاح جهاز جديد لنظام التشغيل Enterprise. -
ردّ الاتصال
الدالة اختيارية
تظهر المَعلمة
callback
على النحو التالي:(response: ArrayBuffer) => void
-
رد
ArrayBuffer
ردّ على التحدي
-
المرتجعات
-
Promise<ArrayBuffer>
Chrome 131 والإصدارات الأحدثتتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير طلبات الاستدعاء لأجل التوافق مع الإصدارات القديمة. ولا يمكنك استخدام كليهما في طلب الدالة نفسه. يتم حلّ الوعد بالنوع نفسه الذي يتم تمريره إلى دالة الاستدعاء.
challengeUserKey()
chrome.enterprise.platformKeys.challengeUserKey(
challenge: ArrayBuffer,
registerKey: boolean,
callback?: function,
)
استخدِم challengeKey
بدلاً من ذلك.
يطلب الجهاز المستخدم مفتاح مستخدم المؤسسة المستند إلى الجهاز ويرسل الردّ كجزء من بروتوكول إثبات الهوية عن بُعد. لا تكون هذه الميزة مفيدة إلا على نظام التشغيل ChromeOS وجنبًا إلى جنب مع واجهة برمجة التطبيقات Verified Access Web API التي تُصدر التحديات وتُحقّق من الردود. إنّ إتمام عملية التحقّق من خلال واجهة برمجة التطبيقات Verified Access Web API هو مؤشر قوي على كل ما يلي: * الجهاز الحالي هو جهاز ChromeOS شرعي. * تتم إدارة الجهاز الحالي من خلال النطاق المحدَّد أثناء إثبات الملكية. * يُدار المستخدم المُسجِّل الدخول حاليًا من خلال النطاق المحدّد أثناء عملية إثبات الملكية. * تتوافق حالة الجهاز الحالية مع سياسة مستخدمي الإصدار المخصّص للمؤسسات. على سبيل المثال، قد تحدّد السياسة أنّه يجب ألا يكون الجهاز في وضع المطوّر. * إنّ المفتاح العام الذي يُرسِله عملية التحقّق مرتبط ارتباطًا وثيقًا بجهازك الحالي والمستخدم الحالي الذي سجّل الدخول. هذه الوظيفة مقيّدة للغاية ولن تنجح إذا لم يكن الجهاز الحالي مُدارًا أو المستخدم الحالي مُدارًا أو إذا لم يتم تفعيل هذه العملية صراحةً للمتصل من خلال سياسة مستخدمي المؤسسة. لا يتوفّر مفتاح مستخدم Enterprise في الرمز المميّز "user"
ولا يمكن الوصول إليه من خلال أي واجهة برمجة تطبيقات أخرى.
المعلمات
-
تحدّي
ArrayBuffer
تحدّي يُرسله Verified Access Web API
-
registerKey
قيمة منطقية
في حال ضبطها، يتم تسجيل مفتاح "مستخدم المؤسسة" الحالي باستخدام الرمز المميّز
"user"
ويتخلّى عن دور "مفتاح مستخدم المؤسسة". ويمكن بعد ذلك ربط المفتاح بشهادة واستخدامه مثل أي مفتاح توقيع آخر. هذا المفتاح هو مفتاح RSA بسعة 2048 بت. ستؤدي المكالمات اللاحقة إلى هذه الدالة إلى إنشاء مفتاح مستخدم جديد في Enterprise. -
ردّ الاتصال
الدالة اختيارية
تظهر المَعلمة
callback
على النحو التالي:(response: ArrayBuffer) => void
-
رد
ArrayBuffer
ردّ على التحدي
-
المرتجعات
-
Promise<ArrayBuffer>
الإصدار 131 من Chrome والإصدارات الأحدثتتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير طلبات الاستدعاء لأجل التوافق مع الإصدارات القديمة. ولا يمكنك استخدام كليهما في طلب الدالة نفسه. يتم حلّ الوعد بالنوع نفسه الذي يتم تمريره إلى دالة الاستدعاء.
getCertificates()
chrome.enterprise.platformKeys.getCertificates(
tokenId: string,
callback?: function,
)
عرض قائمة بجميع شهادات العميل المتاحة من الرمز المميّز المحدّد يمكن استخدامها للتحقّق من توفّر شهادات العميل وانتهاء صلاحيتها والتي يمكن استخدامها لمصادقة معيّنة.
المعلمات
-
tokenId
سلسلة
رقم تعريف الرمز المميّز الذي يعرضه
getTokens
-
ردّ الاتصال
الدالة اختيارية
تظهر المَعلمة
callback
على النحو التالي:(certificates: ArrayBuffer[]) => void
-
الشهادات
ArrayBuffer[]
قائمة الشهادات، كلّ منها بترميز DER لشهادة X.509
-
المرتجعات
-
Promise<ArrayBuffer[]>
الإصدار 131 من Chrome والإصدارات الأحدثتتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير طلبات الاستدعاء لأجل التوافق مع الإصدارات القديمة. ولا يمكنك استخدام كليهما في طلب الدالة نفسه. يتم حلّ الوعد بالنوع نفسه الذي يتم تمريره إلى دالة الاستدعاء.
getTokens()
chrome.enterprise.platformKeys.getTokens(
callback?: function,
)
عرض الرموز المتاحة في جلسة مستخدم عادي، ستحتوي القائمة دائمًا على رمز مميّز للمستخدم مع id
"user"
. إذا كان رمز TPM متاحًا على مستوى النظام، ستتضمّن القائمة المعروضة أيضًا الرمز المميّز على مستوى النظام مع id
"system"
. سيكون الرمز المميّز على مستوى النظام هو نفسه لجميع الجلسات على هذا الجهاز (الجهاز يشير إلى جهاز Chromebook مثلاً).
المعلمات
-
ردّ الاتصال
الدالة اختيارية
تظهر المَعلمة
callback
على النحو التالي:(tokens: Token[]) => void
-
الرموز المميزة
قائمة الرموز المميزة المتاحة
-
المرتجعات
-
Promise<Token[]>
Chrome 131 والإصدارات الأحدثتتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير طلبات الاستدعاء لأجل التوافق مع الإصدارات القديمة. ولا يمكنك استخدام كليهما في طلب الدالة نفسه. يتم حلّ الوعد بالنوع نفسه الذي يتم تمريره إلى دالة الاستدعاء.
importCertificate()
chrome.enterprise.platformKeys.importCertificate(
tokenId: string,
certificate: ArrayBuffer,
callback?: function,
)
تستورد certificate
إلى الرمز المميّز المحدّد إذا كان المفتاح المُعتمَد مخزّنًا في هذا الرمز المميّز. بعد إرسال طلب شهادة بنجاح، يجب استخدام هذه الوظيفة لتخزين الشهادة التي تم الحصول عليها وإتاحتها لنظام التشغيل والمتصفّح من أجل المصادقة.
المعلمات
-
tokenId
سلسلة
رقم تعريف الرمز المميّز الذي يعرضه
getTokens
-
الشهادة
ArrayBuffer
ترميز DER لشهادة X.509
-
ردّ الاتصال
الدالة اختيارية
تظهر المَعلمة
callback
على النحو التالي:() => void
المرتجعات
-
Promise<void>
الإصدار 131 من Chrome والإصدارات الأحدثتتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير طلبات الاستدعاء لأجل التوافق مع الإصدارات القديمة. ولا يمكنك استخدام كليهما في طلب الدالة نفسه. يتم حلّ الوعد بالنوع نفسه الذي يتم تمريره إلى دالة الاستدعاء.
removeCertificate()
chrome.enterprise.platformKeys.removeCertificate(
tokenId: string,
certificate: ArrayBuffer,
callback?: function,
)
تزيل certificate
من الرمز المميّز المحدّد في حال توفّره. يجب استخدامها لإزالة الشهادات القديمة كي لا يتم أخذها في الاعتبار أثناء المصادقة ولا تؤدي إلى تشويش خيار الشهادة. يجب استخدامه لإخلاء مساحة تخزين في متجر الشهادات.
المعلمات
-
tokenId
سلسلة
رقم تعريف الرمز المميّز الذي يعرضه
getTokens
-
الشهادة
ArrayBuffer
ترميز DER لشهادة X.509
-
ردّ الاتصال
الدالة اختيارية
تظهر المَعلمة
callback
على النحو التالي:() => void
المرتجعات
-
Promise<void>
Chrome 131 والإصدارات الأحدثتتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير طلبات الاستدعاء لأجل التوافق مع الإصدارات القديمة. ولا يمكنك استخدام كليهما في طلب الدالة نفسه. يتم حلّ الوعد بالنوع نفسه الذي يتم تمريره إلى دالة الاستدعاء.