browser.enterprise.platformKeys

ה-API הזה מיועד רק לתוספים שהותקנו על ידי מדיניות.

חשוב: ה-API הזה פועל רק ב-ChromeOS.

תיאור

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

הרשאות

enterprise.platformKeys

זמינות

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

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

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

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

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

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

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

• יוצרים את החתימה של נתוני בקשת האישור באמצעות השיטה sign() Token (מוגדרת ב-SubtleCrypto).

• ממלאים את בקשת האישור ושולחים אותה לרשות האישורים.

• אם מתקבל אישור, מייבאים אותו באמצעות [enterprise.platformKeys.importCertificate()`[3]

בדוגמה הבאה מוצגת האינטראקציה העיקרית עם ה-API, מלבד היצירה והשליחה של בקשת האישור:

function getUserToken(callback) {
  browser.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) {
  browser.enterprise.platformKeys.importCertificate(userToken.id, certificate);
}

getUserToken(generateAndSign);

סוגים

Algorithm

‫Chrome 110 ואילך ‫browser.* ‎ החל מ-Chrome 148

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

טיפוסים בני מנייה (enum)

"RSA"

"ECDSA"

ChallengeKeyOptions

‫Chrome 110 ואילך ‫browser.* ‎ החל מ-Chrome 148

מאפיינים

• אתגר

  ArrayBuffer

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

• registerKey

  ‫RegisterKeyOptions אופציונלי

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

• היקף

  היקף

  איזה מפתח Enterprise לאמת.

RegisterKeyOptions

‫Chrome 110 ואילך ‫browser.* ‎ החל מ-Chrome 148

מאפיינים

• אלגוריתם

  אלגוריתם

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

Scope

‫Chrome 110 ואילך ‫browser.* ‎ החל מ-Chrome 148

אם להשתמש במפתח המשתמש בגרסה הארגונית או במפתח המכונה של Enterprise.

טיפוסים בני מנייה (enum)

"USER"

"MACHINE"

Token

מאפיינים

• id [מזהה]

  מחרוזת

  מזהה באופן ייחודי את Token.

  המזהים הסטטיים הם "user" ו-"system", והם מתייחסים לאסימון החומרה הספציפי למשתמש ולאסימון החומרה ברמת המערכת, בהתאמה. יכול להיות ש-enterprise.platformKeys.getTokens יחזיר אסימונים אחרים (עם מזהים אחרים).

• softwareBackedSubtleCrypto

  SubtleCrypto

  ‫Chrome 97 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

  מטמיע את הממשק SubtleCrypto של WebCrypto. הפעולות הקריפטוגרפיות, כולל יצירת המפתחות, מגובות בתוכנה. ההגנה על המפתחות, ולכן גם ההטמעה של המאפיין "לא ניתן לחילוץ", מתבצעת בתוכנה, כך שהמפתחות פחות מוגנים מאשר מפתחות מבוססי חומרה.

  אפשר ליצור רק מפתחות שלא ניתנים לחילוץ. סוג המפתח היחיד שנתמך הוא RSASSA-PKCS1-V1_5 עם modulusLength עד 2048. אפשר להשתמש בכל מפתח כדי לחתום על נתונים פעם אחת לכל היותר, אלא אם התוסף נכלל ברשימת ההיתרים דרך המדיניות KeyPermissions. במקרה כזה, אפשר להשתמש במפתח ללא הגבלה.

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

• subtleCrypto

  SubtleCrypto

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

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

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

Methods

challengeKey()

‫Chrome 110 ואילך ‫browser.* ‎ החל מ-Chrome 148

browser.enterprise.platformKeys.challengeKey(
  options: ChallengeKeyOptions,
): Promise<ArrayBuffer>

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

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

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

פרמטרים

• אפשרויות

  ChallengeKeyOptions

  אובייקט שמכיל את השדות שמוגדרים ב-ChallengeKeyOptions.

החזרות

• Promise<ArrayBuffer>

  ‫Chrome 131 ואילך ‫browser.* ‎ מגרסת Chrome 148

  מחזירה Promise שמתקבלת עם התגובה לאתגר.

challengeMachineKey()

Chrome 50 ואילך browser.* ‎ מגרסה Chrome 148 הוצא משימוש מגרסה Chrome 110

browser.enterprise.platformKeys.challengeMachineKey(
  challenge: ArrayBuffer,
  registerKey?: boolean,
): Promise<ArrayBuffer>

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

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

פרמטרים

• אתגר

  ArrayBuffer

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

• registerKey

  בוליאני אופציונלי

  ‫Chrome 59 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

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

החזרות

• Promise<ArrayBuffer>

  ‫Chrome 131 ואילך ‫browser.* ‎ מגרסת Chrome 148

  מחזירה Promise שמתקבלת עם התגובה לאתגר.

challengeUserKey()

Chrome 50 ואילך browser.* ‎ מגרסה Chrome 148 הוצא משימוש מגרסה Chrome 110

browser.enterprise.platformKeys.challengeUserKey(
  challenge: ArrayBuffer,
  registerKey: boolean,
): Promise<ArrayBuffer>

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

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

פרמטרים

• אתגר

  ArrayBuffer

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

• registerKey

  בוליאני

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

החזרות

• Promise<ArrayBuffer>

  ‫Chrome 131 ואילך ‫browser.* ‎ מגרסת Chrome 148

  מחזירה Promise שמתקבלת עם התגובה לאתגר.

getCertificates()

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

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

פרמטרים

• tokenId

  מחרוזת

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

החזרות

• הבטחה<ArrayBuffer[]>

  ‫Chrome 131 ואילך ‫browser.* ‎ מגרסת Chrome 148

  מחזירה Promise שמתאים לרשימת האישורים הזמינים.

getTokens()

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

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

החזרות

• Promise<Token[]>

  ‫Chrome 131 ואילך ‫browser.* ‎ מגרסת Chrome 148

  הופעל על ידי getTokens עם רשימת הטוקנים הזמינים.

importCertificate()

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

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

פרמטרים

• tokenId

  מחרוזת

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

• אישור

  ArrayBuffer

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

החזרות

• Promise<void>

  ‫Chrome 131 ואילך ‫browser.* ‎ מגרסת Chrome 148

  הפונקציה מחזירה אובייקט Promise שמותאם כשהפעולה מסתיימת.

removeCertificate()

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

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

פרמטרים

• tokenId

  מחרוזת

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

• אישור

  ArrayBuffer

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

החזרות

• Promise<void>

  ‫Chrome 131 ואילך ‫browser.* ‎ מגרסת Chrome 148

  הפונקציה מחזירה אובייקט Promise שמותאם כשהפעולה מסתיימת.