chrome.enterprise.platformKeys

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

תיאור

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

הרשאות

enterprise.platformKeys

זמינות

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

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

שימוש

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

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

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

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

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

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 אחר לא יכול לגשת אליו.

פרמטרים

• options

  ChallengeKeyOptions

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

• callback

  פונקציה אופציונלית

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

  (response: ArrayBuffer) => void

  • תשובה

    ArrayBuffer

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

החזרות

• Promise<ArrayBuffer>

  ‫Chrome 131 ואילך

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

  התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

challengeMachineKey()

Promise Chrome 50+ Deprecated since 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 לגיטימי. * המכשיר הנוכחי מנוהל על ידי הדומיין שצוין במהלך האימות. * המשתמש שמחובר כרגע מנוהל על ידי הדומיין שצוין במהלך האימות. * המצב הנוכחי של המכשיר תואם למדיניות המכשירים של הארגון. לדוגמה, מדיניות יכולה לציין שהמכשיר לא יכול להיות במצב פיתוח. * כל זהות מכשיר שנוצרת על ידי האימות קשורה באופן הדוק לחומרה של המכשיר הנוכחי. הפונקציה הזו מוגבלת מאוד, והיא תיכשל אם המכשיר הנוכחי לא מנוהל, אם המשתמש הנוכחי לא מנוהל או אם הפעולה הזו לא הופעלה באופן מפורש עבור המתקשר על ידי מדיניות המכשיר של הארגון. מפתח המכונה של Enterprise לא נמצא בטוקן "system" ואין אפשרות לגשת אליו דרך אף API אחר.

פרמטרים

• אתגר

  ArrayBuffer

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

• registerKey

  boolean אופציונלי

  ‫Chrome 59+‎

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

• callback

  פונקציה אופציונלית

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

  (response: ArrayBuffer) => void

  • תשובה

    ArrayBuffer

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

החזרות

• Promise<ArrayBuffer>

  ‫Chrome 131 ואילך

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

  התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

challengeUserKey()

Promise Chrome 50+ Deprecated since Chrome 110

chrome.enterprise.platformKeys.challengeUserKey(
  challenge: ArrayBuffer,
  registerKey: boolean,
  callback?: function,
): 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.

• callback

  פונקציה אופציונלית

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

  (response: ArrayBuffer) => void

  • תשובה

    ArrayBuffer

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

החזרות

• Promise<ArrayBuffer>

  ‫Chrome 131 ואילך

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

  התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

getCertificates()

Promise

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

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

פרמטרים

• tokenId

  מחרוזת

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

• callback

  פונקציה אופציונלית

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

  (certificates: ArrayBuffer[]) => void

  • אישורים

    ArrayBuffer[]

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

החזרות

• Promise<ArrayBuffer[]>

  ‫Chrome 131 ואילך

  מחזירה הבטחה (Promise) שנפתרת עם רשימת האישורים הזמינים.

  התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

getTokens()

Promise

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

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

פרמטרים

• callback

  פונקציה אופציונלית

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

  (tokens: Token[]) => void

  • טוקנים

    Token[]

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

החזרות

• Promise<Token[]>

  ‫Chrome 131 ואילך

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

  התמיכה ב-Promises קיימת רק ב-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

  פונקציה אופציונלית

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

  () => void

החזרות

• Promise<void>

  ‫Chrome 131 ואילך

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

  התמיכה ב-Promises קיימת רק ב-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

  פונקציה אופציונלית

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

  () => void

החזרות

• Promise<void>

  ‫Chrome 131 ואילך

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

  התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.