chrome.enterprise.platformKeys

תיאור

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

הרשאות

enterprise.platformKeys

זמינות

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

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

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

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

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

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

"RSA"

"ECDSA"

ChallengeKeyOptions

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

מאפיינים

  • אתגר

    ArrayBuffer

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

  • registerKey

    RegisterKeyOptions אופציונלי

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

  • היקף

    היקף

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

RegisterKeyOptions

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

מאפיינים

  • אלגוריתם

    אלגוריתם

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

Scope

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

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

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.

Methods

challengeKey()

Promise גרסה 110 ואילך של Chrome 
chrome.enterprise.platformKeys.challengeKey(
  options: ChallengeKeyOptions,
  callback?: function,
)

דומה לפונקציות challengeMachineKey ו-challengeUserKey, אבל מאפשרת לציין את האלגוריתם של מפתח רשום. מאתגר מפתח מכונה ארגונית שמבוסס על חומרה ומפיק את התשובה כחלק מפרוטוקול אימות מרחוק. האפשרות הזו שימושית רק ב-ChromeOS ובשילוב עם ממשק ה-API של Verified Access לאינטרנט, שמנפיק את האתגרים ומאמת את התשובות.

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

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

פרמטרים

  • אפשרויות

    ChallengeKeyOptions

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

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

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

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

    (response: ArrayBuffer) => void

    • תשובה

      ArrayBuffer

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

החזרות

  • Promise<ArrayBuffer>

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

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

challengeMachineKey()

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

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

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

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

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

challengeUserKey()

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

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

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

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

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

getCertificates()

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

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

פרמטרים

  • tokenId

    מחרוזת

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

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

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

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

    (certificates: ArrayBuffer[]) => void

    • אישורים

      ArrayBuffer[]

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

החזרות

  • Promise<ArrayBuffer[]>

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

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

getTokens()

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

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

פרמטרים

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

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

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

    (tokens: Token[]) => void

    • טוקנים

      אסימון[]

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

החזרות

  • Promise<Token[]>

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

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

importCertificate()

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

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

פרמטרים

  • tokenId

    מחרוזת

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

  • אישור

    ArrayBuffer

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

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

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

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

    () => void

החזרות

  • Promise<void>

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

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

removeCertificate()

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

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

פרמטרים

  • tokenId

    מחרוזת

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

  • אישור

    ArrayBuffer

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

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

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

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

    () => void

החזרות

  • Promise<void>

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

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