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

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

פרמטרים

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

  • callback

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

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

    (response: ArrayBuffer) => void

    • תשובה

      ArrayBuffer

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

החזרות

  • Promise<ArrayBuffer>

    ‫Chrome 131 ואילך

    ההבטחות נתמכות רק ב-Manifest V3 ובגרסאות מאוחרות יותר. בפלטפורמות אחרות צריך להשתמש בפונקציות Callback.

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 ואילך

    ההבטחות נתמכות רק ב-Manifest V3 ובגרסאות מאוחרות יותר. בפלטפורמות אחרות צריך להשתמש בפונקציות Callback.

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 ואילך

    ההבטחות נתמכות רק ב-Manifest V3 ובגרסאות מאוחרות יותר. בפלטפורמות אחרות צריך להשתמש בפונקציות Callback.

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 ואילך

    ההבטחות נתמכות רק ב-Manifest V3 ובגרסאות מאוחרות יותר. בפלטפורמות אחרות צריך להשתמש בפונקציות Callback.

getTokens()

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

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

פרמטרים

  • callback

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

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

    (tokens: Token[]) => void

    • טוקנים

      טוקן[]

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

החזרות

  • Promise<Token[]>

    ‫Chrome 131 ואילך

    ההבטחות נתמכות רק ב-Manifest V3 ובגרסאות מאוחרות יותר. בפלטפורמות אחרות צריך להשתמש בפונקציות Callback.

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 ואילך

    ההבטחות נתמכות רק ב-Manifest V3 ובגרסאות מאוחרות יותר. בפלטפורמות אחרות צריך להשתמש בפונקציות Callback.

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 ואילך

    ההבטחות נתמכות רק ב-Manifest V3 ובגרסאות מאוחרות יותר. בפלטפורמות אחרות צריך להשתמש בפונקציות Callback.