תיאור
יש להשתמש ב-API chrome.enterprise.platformKeys
כדי ליצור מפתחות ולהתקין אישורים למפתחות האלה. האישורים ינוהלו על ידי הפלטפורמה ואפשר יהיה להשתמש בהם לאימות TLS, לגישה לרשת או באמצעות תוסף אחר דרך chrome.platformKeys.
הרשאות
enterprise.platformKeys
זמינות
מושגים ושימוש
שימוש אופייני ב-API הזה כדי לרשום אישור לקוח כולל את השלבים הבאים:
אפשר לקבל את כל האסימונים הזמינים באמצעות
enterprise.platformKeys.getTokens()
.מוצאים את האסימון ש-
id
שווה ל-"user"
. משתמשים באסימון הזה בהמשך.יצירת זוג מפתחות באמצעות שיטת אסימון
generateKey()
(שמוגדרת ב-SubtleCrypto). הפעולה הזו תחזיר את הכינוי למפתח.מייצאים את המפתח הציבורי באמצעות שיטת האסימון
exportKey()
(כפי שמוגדרת ב-SubtleCrypto).ליצור את החתימה של הנתונים של בקשת האישור באמצעות שיטת האסימון
sign()
(מוגדר ב-SubtleCrypto).ממלאים את בקשת האישור ושולחים אותה לרשות האישורים.
אם התקבל אישור, מייבאים אותו באמצעות [
enterprise.platformKeys.importCertificate()
`[3]
הדוגמה הבאה ממחישה את האינטראקציה העיקרית עם ה-API, מלבד הבנייה והשליחה של בקשת האישור:
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
תכונות
-
אתגר
ArrayBuffer
אתגר שנוצר על ידי Verified Access Web API.
-
registerKey
RegisterKeyOptions אופציונלי
אם קיים, רושם את המפתח המאומת עם האסימון של
scope
שצוין. לאחר מכן אפשר לשייך את המפתח לאישור ולהשתמש בו כמו בכל מפתח חתימה אחר. הקריאות הבאות לפונקציה הזו ייצרו מפתח Enterprise חדש בשדהscope
שצוין. -
היקף
איזה מפתח Enterprise לאתגר.
RegisterKeyOptions
תכונות
-
אלגוריתם
איזה אלגוריתם צריך להשתמש במפתח הרשום.
Scope
האם להשתמש במפתח משתמש Enterprise או במפתח מכונה ארגונית.
טיפוסים בני מנייה (enum)
"USER"
Token
תכונות
-
id
string
מזהה באופן ייחודי את
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.enterprise.platformKeys.challengeKey(
options: ChallengeKeyOptions,
callback: function,
)
דומה ל-challengeMachineKey
ול-challengeUserKey
, אבל מאפשר לציין את האלגוריתם של מפתח רשום. אימות של מפתח Enterprise Machine המגובה בחומרה ופלוט התגובה כחלק מפרוטוקול אימות (attestation) מרחוק. שימושי רק ב-Chrome OS ובשילוב עם Verified Access Web API, שגם יוצר אתגרים וגם מאמת את התשובות.
אימות מוצלח על ידי ה-Verified Access Web API הוא סימן ברור לכך שהמכשיר הנוכחי הוא מכשיר Chrome OS חוקי, המכשיר הנוכחי מנוהל על ידי הדומיין שצוין במהלך האימות, המשתמש המחובר הנוכחי מנוהל על ידי הדומיין שצוין במהלך האימות ומצב המכשיר הנוכחי תואם למדיניות המכשיר של הארגון. למשל, מדיניות עשויה לציין שהמכשיר לא יכול להיות במצב פיתוח. כל זהות המכשיר שמונפקת באמצעות האימות קשורה באופן הדוק לחומרה של המכשיר הנוכחי. אם צוין ההיקף "user"
, הזהות מקושרת גם באופן הדוק למשתמש המחובר הנוכחי.
הפונקציה הזו מוגבלת מאוד ותיכשל אם המכשיר הנוכחי לא מנוהל, המשתמש הנוכחי לא מנוהל או אם הפעולה הזו לא הופעלה באופן מפורש עבור מבצע הקריאה על ידי מדיניות המכשיר של הארגון. המפתח המאומת לא נמצא באסימון "system"
או "user"
ולא ניתן לגשת אליו באמצעות ממשק API אחר.
פרמטרים
-
אפשרויות
אובייקט שמכיל את השדות שהוגדרו ב-
ChallengeKeyOptions
. -
קריאה חוזרת (callback)
פונקציה
הפרמטר
callback
נראה כך:(response: ArrayBuffer) => void
-
תשובה
ArrayBuffer
התשובה לאתגר.
-
challengeMachineKey()
chrome.enterprise.platformKeys.challengeMachineKey(
challenge: ArrayBuffer,
registerKey?: boolean,
callback: function,
)
במקומו צריך להשתמש ב-challengeKey
.
אימות של מפתח Enterprise Machine המגובה בחומרה ופלוט התגובה כחלק מפרוטוקול אימות (attestation) מרחוק. שימושי רק ב-Chrome OS ובשילוב עם Verified Access Web API, שגם יוצר אתגרים וגם מאמת את התשובות. אימות מוצלח באמצעות Verified Access Web API הוא סימן ברור לכל הפרטים הבאים: * המכשיר הנוכחי הוא מכשיר Chrome OS חוקי. * המכשיר הנוכחי מנוהל על ידי הדומיין שצוין במהלך האימות. * המשתמש הנוכחי שמחובר לחשבון מנוהל על ידי הדומיין שצוין במהלך האימות. * המצב הנוכחי של המכשיר תואם למדיניות המכשירים של הארגון. למשל, מדיניות עשויה לציין שהמכשיר לא יכול להיות במצב פיתוח. * כל זהות מכשיר שמונפקת במסגרת האימות קשורה היטב לחומרה של המכשיר הנוכחי. הפונקציה הזו מוגבלת מאוד ותיכשל אם המכשיר הנוכחי לא מנוהל, המשתמש הנוכחי לא מנוהל או אם הפעולה הזו לא הופעלה באופן מפורש עבור מבצע הקריאה על ידי מדיניות המכשיר של הארגון. המפתח של Enterprise Machine לא נמצא באסימון "system"
ולא נגיש לאף ממשק API אחר.
פרמטרים
-
אתגר
ArrayBuffer
אתגר שנוצר על ידי Verified Access Web API.
-
registerKey
בוליאני אופציונלי
Chrome 59 ומעלהאם המדיניות מוגדרת, המפתח הנוכחי של Enterprise Machine רשום עם האסימון
"system"
ומבטל את התפקיד של מפתח Enterprise Machine. לאחר מכן אפשר לשייך את המפתח לאישור ולהשתמש בו כמו בכל מפתח חתימה אחר. המפתח הזה הוא RSA של 2,048 ביט. הקריאות הבאות לפונקציה הזו ייצרו מפתח מכונה חדש במהדורת Enterprise. -
קריאה חוזרת (callback)
פונקציה
הפרמטר
callback
נראה כך:(response: ArrayBuffer) => void
-
תשובה
ArrayBuffer
התשובה לאתגר.
-
challengeUserKey()
chrome.enterprise.platformKeys.challengeUserKey(
challenge: ArrayBuffer,
registerKey: boolean,
callback: function,
)
במקומו צריך להשתמש ב-challengeKey
.
בדיקת אתגר של מפתח משתמש Enterprise המגובה בחומרה ופליטת התגובה כחלק מפרוטוקול אימות מרחוק. שימושי רק ב-Chrome OS ובשילוב עם Verified Access Web API, שגם יוצר אתגרים וגם מאמת את התשובות. אימות מוצלח באמצעות Verified Access Web API הוא סימן ברור לכל הפרטים הבאים: * המכשיר הנוכחי הוא מכשיר Chrome OS חוקי. * המכשיר הנוכחי מנוהל על ידי הדומיין שצוין במהלך האימות. * המשתמש הנוכחי שמחובר לחשבון מנוהל על ידי הדומיין שצוין במהלך האימות. * המצב הנוכחי של המכשיר תואם למדיניות המשתמש של הארגון. למשל, מדיניות עשויה לציין שהמכשיר לא יכול להיות במצב פיתוח. * המפתח הציבורי שמנפיק האימות קשור באופן הדוק לחומרה של המכשיר הנוכחי ולמשתמש המחובר הנוכחי. הפונקציה הזו מוגבלת מאוד ותיכשל אם המכשיר הנוכחי לא מנוהל, המשתמש הנוכחי אינו מנוהל או אם הפעולה הזו לא הופעלה באופן מפורש עבור מבצע הקריאה על ידי מדיניות המשתמש של הארגון. מפתח המשתמש הארגוני לא נמצא באסימון "user"
ולא נגיש לאף ממשק API אחר.
פרמטרים
-
אתגר
ArrayBuffer
אתגר שנוצר על ידי Verified Access Web API.
-
registerKey
boolean
אם היא מוגדרת, מפתח Enterprise User הנוכחי רשום באמצעות האסימון
"user"
ומבטל את התפקיד 'מפתח משתמש Enterprise'. לאחר מכן אפשר לשייך את המפתח לאישור ולהשתמש בו כמו בכל מפתח חתימה אחר. המפתח הזה הוא RSA של 2,048 ביט. הקריאות הבאות לפונקציה הזו ייצרו מפתח משתמש ארגוני חדש. -
קריאה חוזרת (callback)
פונקציה
הפרמטר
callback
נראה כך:(response: ArrayBuffer) => void
-
תשובה
ArrayBuffer
התשובה לאתגר.
-
getCertificates()
chrome.enterprise.platformKeys.getCertificates(
tokenId: string,
callback: function,
)
מחזירה את הרשימה של כל אישורי הלקוח הזמינים מהאסימון הנתון. אפשר להשתמש בהרשאה כדי לבדוק אם קיימים אישורי לקוח שאפשר להשתמש בהם לצורך אימות מסוים, והתוקף שלהם פג.
פרמטרים
-
tokenId
string
המזהה של אסימון שהוחזר על ידי
getTokens
. -
קריאה חוזרת (callback)
פונקציה
הפרמטר
callback
נראה כך:(certificates: ArrayBuffer[]) => void
-
אישורים
ArrayBuffer[]
רשימת האישורים, כל אחד מהם בקידוד DER של אישור X.509.
-
getTokens()
chrome.enterprise.platformKeys.getTokens(
callback: function,
)
מחזירה את האסימונים הזמינים. בסשן של משתמש רגיל, הרשימה תמיד תכלול את האסימון של המשתמש עם id
"user"
. אם זמין אסימון TPM ברמת המערכת, הרשימה שהוחזרה תכלול גם את האסימון ברמת המערכת עם "system"
id
. האסימון ברמת המערכת יהיה זהה לכל הסשנים במכשיר הזה (במובן של מכשיר, למשל Chromebook).
פרמטרים
importCertificate()
chrome.enterprise.platformKeys.importCertificate(
tokenId: string,
certificate: ArrayBuffer,
callback?: function,
)
המערכת מייבאת את certificate
לאסימון הנתון אם המפתח שאושר כבר שמור באסימון הזה. לאחר בקשת אישור מוצלחת, יש להשתמש בפונקציה הזו לאחסון האישור שהושג ולהפוך אותו לזמין עבור מערכת ההפעלה והדפדפן לצורך אימות.
פרמטרים
-
tokenId
string
המזהה של אסימון שהוחזר על ידי
getTokens
. -
אישור
ArrayBuffer
קידוד DER של אישור X.509.
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:() => void
removeCertificate()
chrome.enterprise.platformKeys.removeCertificate(
tokenId: string,
certificate: ArrayBuffer,
callback?: function,
)
הפונקציה מסירה את המשתנה certificate
מהאסימון הנתון, אם הוא קיים. יש להשתמש בה כדי להסיר אישורים מיושנים, כדי שלא ייכללו בתהליך האימות וכדי לא ליצור עומס יתר בבחירת האישור. אמור לשמש לפינוי נפח אחסון במאגר האישורים.
פרמטרים
-
tokenId
string
המזהה של אסימון שהוחזר על ידי
getTokens
. -
אישור
ArrayBuffer
קידוד DER של אישור X.509.
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:() => void