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