chrome.enterprise.platformKeys

תיאור

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

הרשאות

enterprise.platformKeys

זמינות

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

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

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

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

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

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

  • מייצאים את המפתח הציבורי באמצעות שיטת האסימון 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)

"ECDSA"

ChallengeKeyOptions

Chrome 110 ומעלה

תכונות

  • אתגר

    ArrayBuffer

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

  • registerKey

    RegisterKeyOptions אופציונלי

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

  • היקף

    היקף

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

RegisterKeyOptions

Chrome 110 ומעלה

תכונות

  • אלגוריתם

    אלגוריתם

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

Scope

Chrome 110 ומעלה

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

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

"USER"

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

פרמטרים

  • אתגר

    ArrayBuffer

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

  • registerKey

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

    Chrome 59 ומעלה

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

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

    פונקציה

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

    (response: ArrayBuffer)=>void

    • תשובה

      ArrayBuffer

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

challengeUserKey()

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

במקומו צריך להשתמש ב-challengeKey.

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

פרמטרים

  • אתגר

    ArrayBuffer

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

  • registerKey

    boolean

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

  • קריאה חוזרת (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 ברמת המערכת, הרשימה שהוחזרה תכלול גם את האסימון ברמת המערכת עם "system" id. האסימון ברמת המערכת יהיה זהה לכל הסשנים במכשיר הזה (במובן של מכשיר, למשל 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