chrome.enterprise.platformKeys

תיאור

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

הרשאות

enterprise.platformKeys

זמינות

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

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

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

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

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

  • ליצור זוג מפתחות באמצעות שיטת האסימון generateKey() (מוגדרת ב-SubtleCrypto). הפעולה הזו תחזיר את הכינוי למפתח.

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

  • יוצרים את החתימה של הנתונים של בקשת האישור באמצעות שיטת האסימון sign() (מוגדרת ב-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 User Key או ב-Enterprise Machine Key.

Enum

"משתמש"

"MACHINE"

Token

מאפיינים

  • id [מזהה]

    מחרוזת

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

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

  • softwareBackedSubtleCrypto

    SubtleCrypto

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

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

    אפשר ליצור רק מפתחות RSASSA-PKCS1-V1_5 שלא ניתנים לחילוץ עם modulusLength עד 2048. כל מפתח יכול לשמש לחתימה על נתונים פעם אחת לכל היותר.

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

  • subtleCrypto

    SubtleCrypto

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

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

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

שיטות

challengeKey()

Chrome 110+ 
chrome.enterprise.platformKeys.challengeKey(
  options: ChallengeKeyOptions,
  callback: function,
)

דומה ל-challengeMachineKey ול-challengeUserKey, אבל מאפשר לציין את האלגוריתם של מפתח רשום. מאתגר מפתח Enterprise Machine שמגובה בחומרה ופולט את התגובה כחלק מפרוטוקול אימות (attestation) מרחוק. האפשרות הזו שימושית רק ב-Chrome OS ובשילוב עם Verified Access Web API, שבודקת בעיות ומאמתת תשובות.

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

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

פרמטרים

  • אפשרויות

    ChallengeKeyOptions

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

  • קריאה חוזרת (callback)

    פונקציה

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

    (response: ArrayBuffer) => void

    • תשובה

      ArrayBuffer

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

challengeMachineKey()

Chrome 50+ הוצא משימוש מאז Chrome 110
chrome.enterprise.platformKeys.challengeMachineKey(
  challenge: ArrayBuffer,
  registerKey?: boolean,
  callback: function,
)

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

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

פרמטרים

  • אתגר

    ArrayBuffer

    אתגר שבוצע על ידי Verified Access Web API.

  • registerKey

    ערך בוליאני אופציונלי

    Chrome 59+

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

  • קריאה חוזרת (callback)

    פונקציה

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

    (response: ArrayBuffer) => void

    • תשובה

      ArrayBuffer

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

challengeUserKey()

Chrome 50+ הוצא משימוש מאז Chrome 110
chrome.enterprise.platformKeys.challengeUserKey(
  challenge: ArrayBuffer,
  registerKey: boolean,
  callback: function,
)

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

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

פרמטרים

  • אתגר

    ArrayBuffer

    אתגר שבוצע על ידי Verified Access Web API.

  • registerKey

    בוליאני

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

  • קריאה חוזרת (callback)

    פונקציה

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

    (response: ArrayBuffer) => void

    • תשובה

      ArrayBuffer

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

getCertificates()

chrome.enterprise.platformKeys.getCertificates(
  tokenId: string,
  callback: function,
)

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

פרמטרים

  • tokenId

    מחרוזת

    המזהה של אסימון שהוחזר על ידי getTokens.

  • קריאה חוזרת (callback)

    פונקציה

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

    (certificates: ArrayBuffer[]) => void

    • אישורים

      ArrayBuffer[]

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

getTokens()

chrome.enterprise.platformKeys.getTokens(
  callback: function,
)

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

פרמטרים

  • קריאה חוזרת (callback)

    פונקציה

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

    (tokens: Token[]) => void

    • אסימונים

      אסימון[]

      רשימת האסימונים הזמינים.

importCertificate()

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

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

פרמטרים

  • tokenId

    מחרוזת

    המזהה של אסימון שהוחזר על ידי getTokens.

  • אישור

    ArrayBuffer

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

  • קריאה חוזרת (callback)

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

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

    () => void

removeCertificate()

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

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

פרמטרים

  • tokenId

    מחרוזת

    המזהה של אסימון שהוחזר על ידי getTokens.

  • אישור

    ArrayBuffer

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

  • קריאה חוזרת (callback)

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

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

    () => void