chrome.enterprise.platformKeys

תיאור

משתמשים ב-chrome.enterprise.platformKeys API כדי ליצור מפתחות ולהתקין אישורים למפתחות האלה. הפלטפורמה תנהל את האישורים, ואפשר להשתמש בהם לאימות TLS, לגישה לרשת או באמצעות תוסף אחר דרך chrome.platformKeys.

הרשאות

enterprise.platformKeys

זמינות

ChromeOS בלבד נדרשת מדיניות

מושגים ושימוש

שימוש אופייני ב-API הזה כדי לרשום אישור לקוח כולל את השלבים הבאים:

  • אפשר לקבל את כל האסימונים הזמינים באמצעות enterprise.platformKeys.getTokens().

  • מחפשים את האסימון עם id ששווה ל-"user". משתמשים באסימון הזה בהמשך.

  • יוצרים זוג מפתחות באמצעות generateKey() Token method (מוגדר ב-SubtleCrypto). הפעולה הזו תחזיר את ה-handle למפתח.

  • מייצאים את המפתח הציבורי באמצעות exportKey() Token method (מוגדר ב-SubtleCrypto).

  • יוצרים את החתימה של נתוני בקשת האישור באמצעות השיטה sign() Token (מוגדרת ב-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

‫Chrome 110 ואילך

סוג המפתח שרוצים ליצור.

Enum

"RSA"

‪"ECDSA"

ChallengeKeyOptions

‫Chrome 110 ואילך

מאפיינים

  • אתגר

    ArrayBuffer

    אתגר כפי שמופק על ידי Verified Access Web API.

  • registerKey

    ‫RegisterKeyOptions אופציונלי

    אם יש מפתח, הוא נרשם עם הטוקן של scope שצוין. אחר כך אפשר לשייך את המפתח לאישור ולהשתמש בו כמו בכל מפתח חתימה אחר. בשיחות הבאות לפונקציה הזו, ייווצר מפתח Enterprise חדש ב-scope שצוין.

  • היקף

    היקף

    איזה מפתח Enterprise צריך לאתגר.

RegisterKeyOptions

‫Chrome 110 ואילך

מאפיינים

  • אלגוריתם

    אלגוריתם

    האלגוריתם שבו צריך להשתמש המפתח הרשום.

Scope

‫Chrome 110 ואילך

האם להשתמש במפתח המשתמש של 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 (ב-Chrome מגרסה 135 ואילך) עם modulusLength עד 2048. כל מפתח RSASSA-PKCS1-V1_5 יכול לשמש לחתימת נתונים פעם אחת לכל היותר, אלא אם התוסף מתווסף לרשימת ההיתרים באמצעות המדיניות KeyPermissions. במקרה כזה, אפשר להשתמש במפתח ללא הגבלה. מפתחות RSA-OAEP נתמכים החל מגרסה 135 של Chrome, ותוספים שנכללים ברשימת ההיתרים באמצעות אותה מדיניות יכולים להשתמש בהם כדי לבטל את העטיפה של מפתחות אחרים.

    אי אפשר להשתמש במפתחות שנוצרו ב-Token מסוים עם אסימונים אחרים, וגם לא עם window.crypto.subtle. באופן דומה, אי אפשר להשתמש בממשק הזה באובייקטים מסוג Key שנוצרו באמצעות window.crypto.subtle.

  • subtleCrypto

    SubtleCrypto

    מיישם את ממשק SubtleCrypto של WebCrypto. פעולות הקריפטוגרפיה, כולל יצירת מפתח, מגובות בחומרה.

    אפשר ליצור רק מפתחות שלא ניתן לחלץ. סוגי המפתחות הנתמכים הם RSASSA-PKCS1-V1_5 ו-RSA-OAEP (בגרסאות Chrome 135 ומעלה) עם modulusLength עד 2048 ו-ECDSA עם namedCurve P-256. אפשר להשתמש בכל מפתח RSASSA-PKCS1-V1_5 ו-ECDSA לחתימה על נתונים פעם אחת לכל היותר, אלא אם התוסף נכלל ברשימת ההיתרים באמצעות מדיניות KeyPermissions. במקרה כזה, אפשר להשתמש במפתח ללא הגבלה. מפתחות RSA-OAEP נתמכים החל מגרסה 135 של Chrome, ותוספים שנכללים ברשימת ההיתרים באמצעות אותה מדיניות יכולים להשתמש בהם כדי לבטל את העטיפה של מפתחות אחרים.

    אי אפשר להשתמש במפתחות שנוצרו ב-Token מסוים עם אסימונים אחרים, וגם לא עם window.crypto.subtle. באופן דומה, אי אפשר להשתמש בממשק הזה באובייקטים מסוג Key שנוצרו באמצעות window.crypto.subtle.

Methods

challengeKey()

‫Chrome 110 ואילך 
chrome.enterprise.platformKeys.challengeKey(
  options: ChallengeKeyOptions,
): Promise<ArrayBuffer>

דומה ל-challengeMachineKey ול-challengeUserKey, אבל מאפשרת לציין את האלגוריתם של מפתח רשום. מאתגר מפתח מכונה ארגוני שמגובה בחומרה ומפיק את התגובה כחלק מפרוטוקול אימות מרחוק. האפשרות הזו שימושית רק ב-ChromeOS ובשילוב עם Verified Access Web API, שגם מנפיק אתגרים וגם מאמת תגובות.

אימות מוצלח באמצעות Verified Access Web API הוא אות חזק לכך שהמכשיר הנוכחי הוא מכשיר ChromeOS לגיטימי, שהמכשיר הנוכחי מנוהל על ידי הדומיין שצוין במהלך האימות, שהמשתמש הנוכחי שמחובר לחשבון מנוהל על ידי הדומיין שצוין במהלך האימות, ושמצב המכשיר הנוכחי תואם למדיניות המכשירים הארגוניים. לדוגמה, מדיניות יכולה לציין שהמכשיר לא יכול להיות במצב פיתוח. כל זהות מכשיר שנוצרת על ידי האימות קשורה באופן הדוק לחומרה של המכשיר הנוכחי. אם מצוין היקף "user", הזהות קשורה גם למשתמש הנוכחי שמחובר לחשבון.

הפונקציה הזו מוגבלת מאוד, והיא תיכשל אם המכשיר הנוכחי לא מנוהל, אם המשתמש הנוכחי לא מנוהל או אם הפעולה הזו לא הופעלה באופן מפורש עבור המתקשר על ידי מדיניות המכשיר הארגוני. המפתח שנדרש לא נמצא בטוקן "system" או "user", ואף API אחר לא יכול לגשת אליו.

פרמטרים

החזרות

  • Promise<ArrayBuffer>

    ‫Chrome 131 ואילך

challengeMachineKey()

‫Chrome 50 ואילך הוצא משימוש מאז Chrome 110
chrome.enterprise.platformKeys.challengeMachineKey(
  challenge: ArrayBuffer,
  registerKey?: boolean,
): Promise<ArrayBuffer>

במקום זאת, אתם צריכים להשתמש ב-challengeKey.

מאתגר מפתח מכונה ארגוני שמגובה בחומרה ומפיק את התגובה כחלק מפרוטוקול אימות מרחוק. האפשרות הזו שימושית רק ב-ChromeOS ובשילוב עם Verified Access Web API, שגם מנפיק אתגרים וגם מאמת תגובות. אימות מוצלח באמצעות Verified Access Web API הוא אות חזק לכל אחד מהדברים הבאים: * המכשיר הנוכחי הוא מכשיר ChromeOS לגיטימי. * המכשיר הנוכחי מנוהל על ידי הדומיין שצוין במהלך האימות. * המשתמש שמחובר כרגע מנוהל על ידי הדומיין שצוין במהלך האימות. * המצב הנוכחי של המכשיר תואם למדיניות המכשירים של הארגון. לדוגמה, מדיניות יכולה לציין שהמכשיר לא יכול להיות במצב פיתוח. * כל זהות מכשיר שנוצרת על ידי האימות קשורה באופן הדוק לחומרה של המכשיר הנוכחי. הפונקציה הזו מוגבלת מאוד, והיא תיכשל אם המכשיר הנוכחי לא מנוהל, אם המשתמש הנוכחי לא מנוהל או אם הפעולה הזו לא הופעלה באופן מפורש עבור המתקשר על ידי מדיניות המכשיר הארגוני. מפתח המכונה של Enterprise לא נמצא בטוקן "system" ולא ניתן לגשת אליו באמצעות אף API אחר.

פרמטרים

  • אתגר

    ArrayBuffer

    אתגר כפי שמופק על ידי Verified Access Web API.

  • registerKey

    ‫boolean אופציונלי

    ‫Chrome 59 ואילך

    אם המדיניות מוגדרת, מפתח המכונה הנוכחי של Enterprise נרשם באמצעות הטוקן "system" ומוותר על התפקיד של מפתח המכונה של Enterprise. אחר כך אפשר לשייך את המפתח לאישור ולהשתמש בו כמו בכל מפתח חתימה אחר. המפתח הזה הוא RSA של 2048 ביט. בשיחות הבאות לפונקציה הזו, המערכת תיצור מפתח מכונה חדש של Enterprise.

החזרות

  • Promise<ArrayBuffer>

    ‫Chrome 131 ואילך

challengeUserKey()

‫Chrome 50 ואילך הוצא משימוש מאז Chrome 110
chrome.enterprise.platformKeys.challengeUserKey(
  challenge: ArrayBuffer,
  registerKey: boolean,
): Promise<ArrayBuffer>

במקום זאת, אתם צריכים להשתמש ב-challengeKey.

מאתגר מפתח משתמש ארגוני שמגובה בחומרה, ופולט את התגובה כחלק מפרוטוקול אימות מרחוק. האפשרות הזו שימושית רק ב-ChromeOS ובשילוב עם Verified Access Web API, שגם מנפיק אתגרים וגם מאמת תגובות. אימות מוצלח באמצעות Verified Access Web API הוא אות חזק לכל אחד מהדברים הבאים: * המכשיר הנוכחי הוא מכשיר ChromeOS לגיטימי. * המכשיר הנוכחי מנוהל על ידי הדומיין שצוין במהלך האימות. * המשתמש שמחובר כרגע מנוהל על ידי הדומיין שצוין במהלך האימות. * המצב הנוכחי של המכשיר תואם למדיניות המשתמשים בגרסה הארגונית. לדוגמה, מדיניות יכולה לציין שהמכשיר לא יכול להיות במצב פיתוח. * המפתח הציבורי שנוצר על ידי האימות קשור באופן הדוק לחומרה של המכשיר הנוכחי ולמשתמש הנוכחי שמחובר לחשבון. הפונקציה הזו מוגבלת מאוד, והיא תיכשל אם המכשיר הנוכחי לא מנוהל, אם המשתמש הנוכחי לא מנוהל או אם הפעולה הזו לא הופעלה באופן מפורש עבור המתקשר על ידי מדיניות המשתמשים בארגון. מפתח המשתמש של Enterprise לא נמצא באסימון "user" ולא נגיש לאף API אחר.

פרמטרים

  • אתגר

    ArrayBuffer

    אתגר כפי שמופק על ידי Verified Access Web API.

  • registerKey

    בוליאני

    אם המדיניות מוגדרת, מפתח המשתמש הנוכחי בגרסה הארגונית נרשם עם אסימון "user", והמערכת מוותרת על התפקיד של מפתח המשתמש בגרסה הארגונית. אחר כך אפשר לשייך את המפתח לאישור ולהשתמש בו כמו בכל מפתח חתימה אחר. המפתח הזה הוא RSA של 2048 ביט. שיחות עוקבות לפונקציה הזו ייצרו מפתח חדש של משתמש Enterprise.

החזרות

  • Promise<ArrayBuffer>

    ‫Chrome 131 ואילך

getCertificates()

chrome.enterprise.platformKeys.getCertificates(
  tokenId: string,
): Promise<ArrayBuffer[]>

הפונקציה מחזירה את רשימת כל אישורי הלקוח שזמינים מהאסימון הנתון. אפשר להשתמש בה כדי לבדוק את קיומם של אישורי לקוח שניתן להשתמש בהם לאימות מסוים, ואת תוקפם.

פרמטרים

  • tokenId

    מחרוזת

    המזהה של טוקן שהוחזר על ידי getTokens.

החזרות

  • Promise<ArrayBuffer[]>

    ‫Chrome 131 ואילך

getTokens()

chrome.enterprise.platformKeys.getTokens(): Promise<Token[]>

מחזירה את הטוקנים הזמינים. בסשן של משתמש רגיל, הרשימה תמיד תכיל את האסימון של המשתמש עם id "user". אם יש אסימון TPM ברמת המערכת, הרשימה שמוחזרת תכיל גם את האסימון ברמת המערכת עם id "system". האסימון ברמת המערכת יהיה זהה לכל הסשנים במכשיר הזה (מכשיר במובן של למשל Chromebook).

החזרות

  • Promise<Token[]>

    ‫Chrome 131 ואילך

importCertificate()

chrome.enterprise.platformKeys.importCertificate(
  tokenId: string,
  certificate: ArrayBuffer,
): Promise<void>

מייבא את certificate לטוקן הנתון אם המפתח המאושר כבר מאוחסן בטוקן הזה. אחרי בקשת אישור מוצלחת, צריך להשתמש בפונקציה הזו כדי לאחסן את האישור שהתקבל ולהפוך אותו לזמין למערכת ההפעלה ולדפדפן לצורך אימות.

פרמטרים

  • tokenId

    מחרוזת

    המזהה של טוקן שהוחזר על ידי getTokens.

  • אישור

    ArrayBuffer

    קידוד DER של אישור X.509.

החזרות

  • Promise<void>

    ‫Chrome 131 ואילך

removeCertificate()

chrome.enterprise.platformKeys.removeCertificate(
  tokenId: string,
  certificate: ArrayBuffer,
): Promise<void>

מסיר את certificate מהאסימון הנתון, אם הוא קיים. צריך להשתמש בה כדי להסיר אישורים שיצאו משימוש, כדי שלא ייכללו בתהליך האימות ולא יפריעו לבחירת האישור. צריך להשתמש בו כדי לפנות מקום באחסון בחנות האישורים.

פרמטרים

  • tokenId

    מחרוזת

    המזהה של טוקן שהוחזר על ידי getTokens.

  • אישור

    ArrayBuffer

    קידוד DER של אישור X.509.

החזרות

  • Promise<void>

    ‫Chrome 131 ואילך