chrome.enterprise.platformKeys

תיאור

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

הרשאות

enterprise.platformKeys

זמינות

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

שימוש

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

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

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

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

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

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

"ECDSA"

ChallengeKeyOptions

גרסה 110 ואילך של Chrome

מאפיינים

  • אתגר

    ArrayBuffer

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

  • registerKey

    RegisterKeyOptions אופציונלי

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

  • היקף

    היקף

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

RegisterKeyOptions

Chrome 110+

מאפיינים

  • אלגוריתם

    אלגוריתם

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

Scope

Chrome 110+

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

Enum

Token

מאפיינים

  • id [מזהה]

    מחרוזת

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

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

  • softwareBackedSubtleCrypto

    SubtleCrypto

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

    הטמעת ממשק 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) מרחוק. האפשרות הזו שימושית רק ב-ChromeOS ובשילוב עם Verified Access Web API, שמוסיף אתגרים וגם מאמת תשובות.

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

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

פרמטרים

  • אפשרויות

    ChallengeKeyOptions

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

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

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

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

    (response: ArrayBuffer) => void

    • תשובה

      ArrayBuffer

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

החזרות

  • Promise&lt;ArrayBuffer&gt;

    בהמתנה

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

challengeMachineKey()

Promise Chrome מגרסה 50 ואילך הופסקה השימוש ב-Chrome מגרסה 110
chrome.enterprise.platformKeys.challengeMachineKey(
  challenge: ArrayBuffer,
  registerKey?: boolean,
  callback?: function,
)

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

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

פרמטרים

  • אתגר

    ArrayBuffer

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

  • registerKey

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

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

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

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

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

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

    (response: ArrayBuffer) => void

    • תשובה

      ArrayBuffer

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

החזרות

  • Promise&lt;ArrayBuffer&gt;

    בהמתנה

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

challengeUserKey()

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

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

מאתגר מפתח משתמש Enterprise שמגובה בחומרה ופולט את התגובה כחלק מפרוטוקול אימות (attestation) מרחוק. האפשרות הזו שימושית רק ב-ChromeOS ובשילוב עם 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

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

החזרות

  • Promise&lt;ArrayBuffer&gt;

    בהמתנה

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

getCertificates()

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

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

פרמטרים

  • tokenId

    מחרוזת

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

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

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

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

    (certificates: ArrayBuffer[]) => void

    • אישורים

      ArrayBuffer[]

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

החזרות

  • Promise&lt;ArrayBuffer[]&gt;

    בהמתנה

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

getTokens()

הבטחה 
chrome.enterprise.platformKeys.getTokens(
  callback?: function,
)

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

פרמטרים

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

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

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

    (tokens: Token[]) => void

    • טוקנים

      אסימון[]

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

החזרות

  • Promise<Token[]>

    בהמתנה

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

importCertificate()

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

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

פרמטרים

  • tokenId

    מחרוזת

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

  • אישור

    ArrayBuffer

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

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

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

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

    () => void

החזרות

  • הבטחה<Empty>

    בהמתנה

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

removeCertificate()

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

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

פרמטרים

  • tokenId

    מחרוזת

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

  • אישור

    ArrayBuffer

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

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

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

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

    () => void

החזרות

  • הבטחה<Empty>

    בהמתנה

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