chrome.enterprise.platformKeys

refresh date: 2026-09-25 robots: noindex

תיאור

משתמשים ב-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

בדוגמה הבאה מוצגת האינטראקציה העיקרית עם ה-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.

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

"USER"

"MACHINE"

Token

מאפיינים

  • id [מזהה]

    מחרוזת

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

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

  • softwareBackedSubtleCrypto

    SubtleCrypto

    ‫Chrome מגרסה 97 ואילך

    מטמיע את הממשק 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()

Promise Chrome 110+‎ 
chrome.enterprise.platformKeys.challengeKey(
  options: ChallengeKeyOptions,
  callback?: function,
): Promise<ArrayBuffer>

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

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

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

פרמטרים

  • אפשרויות

    ChallengeKeyOptions

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

  • callback

    function optional

    הפרמטר callback נראה כך: 

    (response: ArrayBuffer) => void

    • תשובה

      ArrayBuffer

      התשובה לאתגר.

החזרות

  • Promise<ArrayBuffer>

    ‫Chrome מגרסה 131 ואילך

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

    הבטחות נתמכות רק ב-Manifest V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callbacks).

challengeMachineKey()

Promise Chrome 50 ואילך הוצא משימוש החל מגרסה Chrome 110
chrome.enterprise.platformKeys.challengeMachineKey(
  challenge: ArrayBuffer,
  registerKey?: boolean,
  callback?: function,
): Promise<ArrayBuffer>

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

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

פרמטרים

  • אתגר

    ArrayBuffer

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

  • registerKey

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

    Chrome 59 ואילך

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

  • callback

    function optional

    הפרמטר callback נראה כך: 

    (response: ArrayBuffer) => void

    • תשובה

      ArrayBuffer

      התשובה לאתגר.

החזרות

  • Promise<ArrayBuffer>

    ‫Chrome מגרסה 131 ואילך

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

    הבטחות נתמכות רק ב-Manifest V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callbacks).

challengeUserKey()

Promise Chrome 50 ואילך הוצא משימוש החל מגרסה Chrome 110
chrome.enterprise.platformKeys.challengeUserKey(
  challenge: ArrayBuffer,
  registerKey: boolean,
  callback?: function,
): 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 ביט. קריאות נוספות לפונקציה הזו ייצרו מפתח חדש למשתמש בגרסה הארגונית.

  • callback

    function optional

    הפרמטר callback נראה כך: 

    (response: ArrayBuffer) => void

    • תשובה

      ArrayBuffer

      התשובה לאתגר.

החזרות

  • Promise<ArrayBuffer>

    ‫Chrome מגרסה 131 ואילך

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

    הבטחות נתמכות רק ב-Manifest V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callbacks).

getCertificates()

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

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

פרמטרים

  • tokenId

    מחרוזת

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

  • callback

    function optional

    הפרמטר callback נראה כך: 

    (certificates: ArrayBuffer[]) => void

    • אישורים

      ArrayBuffer[]‎

      רשימת האישורים, כל אחד בקידוד DER של אישור X.509.

החזרות

  • הבטחה<ArrayBuffer[]>

    ‫Chrome מגרסה 131 ואילך

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

    הבטחות נתמכות רק ב-Manifest V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callbacks).

getTokens()

Promise 
chrome.enterprise.platformKeys.getTokens(
  callback?: function,
): Promise<Token[]>

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

פרמטרים

  • callback

    function optional

    הפרמטר callback נראה כך: 

    (tokens: Token[]) => void

    • טוקנים

      טוקן[]

      רשימת הטוקנים הזמינים.

החזרות

  • Promise<Token[]>

    ‫Chrome מגרסה 131 ואילך

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

    הבטחות נתמכות רק ב-Manifest V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callbacks).

importCertificate()

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

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

פרמטרים

  • tokenId

    מחרוזת

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

  • אישור

    ArrayBuffer

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

  • callback

    function optional

    הפרמטר callback נראה כך: 

    () => void

החזרות

  • Promise<void>

    ‫Chrome מגרסה 131 ואילך

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

    הבטחות נתמכות רק ב-Manifest V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callbacks).

removeCertificate()

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

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

פרמטרים

  • tokenId

    מחרוזת

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

  • אישור

    ArrayBuffer

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

  • callback

    function optional

    הפרמטר callback נראה כך: 

    () => void

החזרות

  • Promise<void>

    ‫Chrome מגרסה 131 ואילך

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

    הבטחות נתמכות רק ב-Manifest V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callbacks).