chrome.platformKeys

תיאור

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

הרשאות

platformKeys

זמינות

Chrome 45+ ChromeOS בלבד

סוגים

ClientCertificateRequest

מאפיינים

  • certificateAuthorities

    ArrayBuffer[]

    רשימת שמות ייחודיים של רשויות אישורים שמותרות על ידי השרת. כל רשומה חייבת להיות מסוג X.509 DistinguishedName בקידוד DER.

  • certificateTypes

    ClientCertificateType[]

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

ClientCertificateType

Enum

"rsaSign"

"ecdsaSign"

Match

מאפיינים

  • אישור

    ArrayBuffer

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

  • keyAlgorithm

    אובייקט

    ה-KeyAlgorithm של המפתח שאושר. האישור מכיל פרמטרים של אלגוריתם שטבועים במפתח של האישור (למשל אורך המפתח). פרמטרים אחרים כמו פונקציית הגיבוב (hash) שמשמשת את פונקציית הסימן לא נכללים.

SelectDetails

מאפיינים

  • clientCerts

    ArrayBuffer[] אופציונלי

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

  • אינטראקטיבי

    בוליאני

    אם הערך הוא True, הרשימה המסוננת מוצגת למשתמש כדי שיוכל לבחור אישור באופן ידני, ובכך להעניק לתוסף גישה לאישורים ולמפתחות. רק האישורים שנבחרו יוחזרו. אם הוא מוגדר כ-False, הרשימה תצטמצם לכל האישורים שלתוסף ניתנה גישה אליהם (באופן אוטומטי או ידני).

  • יוחזרו רק אישורים שתואמים לבקשה הזו.

VerificationDetails

מאפיינים

  • hostname

    מחרוזת

    שם המארח של השרת שעבורו יש לאמת את האישור, למשל. השרת שהציג את serverCertificateChain.

  • serverCertificateChain

    ArrayBuffer[]

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

VerificationResult

מאפיינים

  • debug_errors

    String[]

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

    הערה: הרשימה הזו מיועדת לניפוי באגים בלבד, וייתכן שהיא לא תכלול את כל השגיאות הרלוונטיות. השגיאות שמוחזרות עשויות להשתנות בגרסאות עתידיות של ה-API הזה, ולא בטוח שיהיו תואמות להרצה או לאחור.

  • אמינה

    בוליאני

    התוצאה של אימות המהימנות: True אם ניתן לקבוע את האמינות של פרטי האימות הנתונים ו-FALSE אם האמון נדחה מסיבה כלשהי.

שיטות

getKeyPair()

chrome.platformKeys.getKeyPair(
  certificate: ArrayBuffer,
  parameters: object,
  callback: function,
)

מעביר את זוג המפתחות של certificate לשימוש עם platformKeys.subtleCrypto אל callback.

פרמטרים

  • אישור

    ArrayBuffer

    האישור של Match שהוחזר על ידי selectClientCertificates.

  • פרמטרים

    אובייקט

    ההגדרה הזו קובעת את הפרמטרים של אלגוריתם החתימה/הגיבוב בנוסף לפרמטרים שהמפתח עצמו קובע. אותם פרמטרים מתקבלים כמו בפונקציה importKey של WebCrypto, למשל. RsaHashedImportParams למפתח RSASSA-PKCS1-v1_5 ו-EcKeyImportParams למפתח EC. בנוסף, למפתחות RSASSA-PKCS1-v1_5, ניתן לציין פרמטר של שם אלגוריתם גיבוב (hashing) עם אחד מהערכים הבאים: 'none', 'SHA-1', 'SHA-256', 'SHA-384' או 'SHA-512', למשל {"hash": { "name": "none" } } לאחר מכן פונקציית הסימן תחיל מרווח פנימי מסוג PKCS#1 v1.5 אבל לא תגבב את הנתונים הנתונים.

    נכון לעכשיו, השיטה הזו תומכת רק בפורמט RSASSA-PKCS1-v1_5 ו-ECDSA אלגוריתמים.

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

    פונקציה

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

    (publicKey: object, privateKey?: object) => void

    • publicKey

      אובייקט

    • privateKey

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

      הכתובת עשויה להיות null אם לתוסף הזה אין גישה אליו.

getKeyPairBySpki()

Chrome 85+ 
chrome.platformKeys.getKeyPairBySpki(
  publicKeySpkiDer: ArrayBuffer,
  parameters: object,
  callback: function,
)

מעביר את זוג המפתחות שזוהה על ידי publicKeySpkiDer לשימוש עם platformKeys.subtleCrypto אל callback.

פרמטרים

  • publicKeySpkiDer

    ArrayBuffer

    SubjectPublicKeyInfo בקידוד X.509 של DER, שמתקבל לדוגמה באמצעות קריאה לפונקציית exportKey של WebCrypto באמצעות format="spki" .

  • פרמטרים

    אובייקט

    מספקת פרמטרים של אלגוריתם חתימה וגיבוב, בנוסף לאלה שתוקנו על ידי המפתח עצמו. אותם פרמטרים מתקבלים כמו בפונקציה importKey של WebCrypto, למשל. RsaHashedImportParams למפתח RSASSA-PKCS1-v1_5. למפתחות RSASSA-PKCS1-v1_5, אנחנו צריכים גם להעביר "hash" הפרמטר { "hash": { "name": string } }. 'גיבוב' מייצג את השם של אלגוריתם הגיבוב (hashing) שיש להשתמש בו בפעולת התקציר לפני סימן. אפשר להעביר את הערך 'None' בתור שם הגיבוב (hash). במקרה כזה, פונקציית הסימן תחיל מרווח פנימי של PKCS#1 v1.5 ולא תגבב את הנתונים הנתונים.

    נכון לעכשיו, השיטה הזו תומכת ב-ECDSA אלגוריתם עם עקומה P-256 בעלת שם ו-RSASSA-PKCS1-v1_5 אחד מהאלגוריתמים לגיבוב (none), SHA-1, SHA-256, SHA-384 ו-SHA-512.

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

    פונקציה

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

    (publicKey: object, privateKey?: object) => void

    • publicKey

      אובייקט

    • privateKey

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

      הכתובת עשויה להיות null אם לתוסף הזה אין גישה אליו.

selectClientCertificates()

הבטחה 
chrome.platformKeys.selectClientCertificates(
  details: SelectDetails,
  callback?: function,
)

השיטה הזו מסננת מתוך רשימה של אישורי לקוח את האישורים המוכרים לפלטפורמה, שתואמים ל-request ושלתוסף יש להם הרשאת גישה לאישור ולמפתח הפרטי שלו. אם הערך של interactive הוא True, מוצגת למשתמש תיבת דו-שיח שבה הוא יכול לבחור מבין האישורים התואמים ולהעניק לתוסף גישה לאישור. אישורי הלקוח שנבחרו/מסוננים יועברו אל callback.

פרמטרים

  • פרטים

    SelectDetails

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

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

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

    (matches: Match[]) => void

    • תואם את:

      התאמה[]

      רשימת האישורים שתואמים לבקשה, שלתוסף יש הרשאה עבורו וכן, אם הערך של interactive הוא True, שנבחרו על ידי המשתמש.

החזרות

  • הבטחה<התאמה[]>

    Chrome 121 ואילך

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

subtleCrypto()

chrome.platformKeys.subtleCrypto()

הטמעה של SubtleCrypto של WebCrypto שמאפשר לבצע פעולות הצפנה במפתחות של אישורי לקוח שזמינים לתוסף הזה.

החזרות

  • object | לא מוגדר

verifyTLSServerCertificate()

הבטחה 
chrome.platformKeys.verifyTLSServerCertificate(
  details: VerificationDetails,
  callback?: function,
)

הפונקציה בודקת אם אפשר להגדיר אמון ב-details.serverCertificateChain עבור details.hostname בהתאם להגדרות האמינות של הפלטפורמה. הערה: ההתנהגות בפועל של אימות האמינות לא מפורטת במלואה ועשויה להשתנות בעתיד. הטמעת ה-API מאמתת את תפוגת האישור, מאמתת את נתיב האישור ובודקת את האמינות של רשות אישורים ידועה. ההטמעה אמורה לפעול בהתאם ל-eKU serverAuth ולתמוך בשמות חלופיים של נושא.

פרמטרים

החזרות

  • Promise&lt;VerificationResult&gt;

    Chrome 121 ואילך

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