chrome.enterprise.platformKeys

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

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

תיאור

משתמשים ב-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

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

סוג המפתח שרוצים ליצור.

Enum

ChallengeKeyOptions

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

מאפיינים

• אתגר

  ArrayBuffer

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

• registerKey

  RegisterKeyOptions אופציונלי

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

• היקף

  היקף

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

RegisterKeyOptions

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

מאפיינים

• אלגוריתם

  אלגוריתם

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

Scope

Chrome 110+

האם להשתמש ב-Enterprise User Key או ב-Enterprise Machine Key.

Enum

"USER"

"MACHINE"

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 ובשילוב עם ממשק ה-API של Verified Access לאינטרנט, שמנפיק את האתגרים ומאמת את התשובות.

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

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

פרמטרים

• אפשרויות

  ChallengeKeyOptions

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

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

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

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

  (response: ArrayBuffer) => void

  • תשובה

    ArrayBuffer

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

החזרות

• Promise<ArrayBuffer>

  בהמתנה

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

challengeMachineKey()

הבטחה Chrome מגרסה 50 ואילך הוצא משימוש מאז Chrome 110

chrome.enterprise.platformKeys.challengeMachineKey(
  challenge: ArrayBuffer,
  registerKey?: boolean,
  callback?: function,
)

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

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

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

החזרות

• Promise<ArrayBuffer>

  בהמתנה

  הבטחות נתמכות במניפסט מגרסה 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

  בוליאני

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

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

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

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

  (response: ArrayBuffer) => void

  • תשובה

    ArrayBuffer

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

החזרות

• Promise<ArrayBuffer>

  בהמתנה

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

getCertificates()

הבטחה

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

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

פרמטרים

• tokenId

  מחרוזת

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

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

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

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

  (certificates: ArrayBuffer[]) => void

  • אישורים

    ArrayBuffer[]

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

החזרות

• Promise<ArrayBuffer[]>

  בהמתנה

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

getTokens()

הבטחה

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

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

פרמטרים

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

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

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

  (tokens: Token[]) => void

  • אסימונים

    אסימון[]

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

החזרות

• Promise<Token[]>

  בהמתנה

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

importCertificate()

Promise

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

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

פרמטרים

• tokenId

  מחרוזת

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

• אישור

  ArrayBuffer

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

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

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

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

  () => void

החזרות

• הבטחה<Empty>

  בהמתנה

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

removeCertificate()

Promise

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

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

פרמטרים

• tokenId

  מחרוזת

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

• אישור

  ArrayBuffer

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

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

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

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

  () => void

החזרות

• הבטחה<Empty>

  בהמתנה

  יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.