תיאור
אפשר להשתמש ב-API chrome.platformKeys
כדי לגשת לאישורי לקוח שמנוהלים על ידי הפלטפורמה. אם המשתמש או המדיניות מעניקים את ההרשאה, תוסף יכול להשתמש באישור כזה בפרוטוקול האימות המותאם אישית שלו. לדוגמה כך מתאפשר שימוש באישורים שמנוהלים על ידי פלטפורמה ברשתות VPN של צד שלישי (מידע נוסף זמין בכתובת chrome.vpnProvider).
הרשאות
platformKeys
זמינות
סוגים
ClientCertificateRequest
מאפיינים
-
certificateAuthorities
ArrayBuffer[]
רשימת שמות ייחודיים של רשויות אישורים שמותרות על ידי השרת. כל רשומה חייבת להיות מסוג X.509 DistinguishedName בקידוד DER.
-
certificateTypes
השדה הזה הוא רשימה של סוגי האישורים המבוקשים, והם ממוינים לפי העדפת השרת. המערכת תאחזר רק אישורים מסוג שנכלל ברשימה הזו. עם זאת, אם
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.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
.
פרמטרים
החזרות
-
הבטחה<התאמה[]>
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 ולתמוך בשמות חלופיים של נושא.
פרמטרים
-
פרטים
-
קריאה חוזרת (callback)
פונקציה אופציונלית
הפרמטר
callback
נראה כך:(result: VerificationResult) => void
-
תוצאה
-
החזרות
-
Promise<VerificationResult>
Chrome 121 ואילךהבטחות נתמכות במניפסט מגרסה V3 ואילך, אבל ניתנות קריאות חוזרות (callback) בשביל תאימות לאחור. לא ניתן להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה הזו מצליחה לפתור את הבעיה באותו סוג שמועבר לקריאה החוזרת.