תיאור
יש להשתמש ב-API הזה כדי לחשוף אישורים לפלטפורמה שיכולה להשתמש באישורים האלה לאימותי TLS.
הרשאות
certificateProvider
זמינות
מושגים ושימוש
כשמשתמשים ב-API הזה בדרך כלל כדי לחשוף אישורי לקוח ל-ChromeOS, צריך לפעול לפי השלבים הבאים:
- התוסף נרשם לאירועים
onCertificatesUpdateRequested
ו-onSignatureRequested
. - התוסף קורא לפונקציה
setCertificates()
כדי לספק את הרשימה הראשונית של האישורים לאחר האתחול. - התוסף עוקב אחר השינויים ברשימת הקריאות והאישורים הזמינים
setCertificates()
כדי להודיע לדפדפן על כל שינוי כזה. - במהלך לחיצת יד בפרוטוקול TLS, הדפדפן מקבל בקשת אישור לקוח. באירוע
onCertificatesUpdateRequested
, הדפדפן מבקש מהתוסף לדווח על כל האישורים שהוא מספק כרגע. - התוסף מדווח חזרה עם האישורים הזמינים כעת, באמצעות השיטה
setCertificates()
. - הדפדפן מתאים את כל האישורים הזמינים לבקשת אישור הלקוח מהמארח המרוחק. ההתאמות מוצגות למשתמש בתיבת דו-שיח של בחירה.
- המשתמש יכול לבחור אישור ובכך לאשר את האימות או לבטל את האימות.
![תיבת דו-שיח לבחירת אישור](https://developer.chrome.google.cn/static/docs/extensions/reference/api/images/certificate_provider_selection_dialog.png?authuser=5&hl=he)
- אם המשתמש מבטל את האימות או שלא נמצא אישור שתואם לבקשה, אימות לקוח ה-TLS יבוטל.
- אחרת, אם המשתמש יאשר את האימות באמצעות אישור שסופק על ידי התוסף, הדפדפן יבקש מהתוסף לחתום על הנתונים כדי להמשיך את לחיצת היד בפרוטוקול TLS. הבקשה נשלחת כאירוע
onSignatureRequested
. - האירוע הזה מכיל נתוני קלט. הוא מצהיר באיזה אלגוריתם צריך להשתמש כדי ליצור את החתימה, ומתייחס לאחד מהאישורים שדווחו על ידי התוסף הזה. התוסף חייב ליצור חתימה עבור הנתונים הנתונים באמצעות המפתח הפרטי שמשויך לאישור ההפניה. יכול להיות שצריך ליצור את החתימה כדי להוסיף תקציר (DigestInfo) ולהוסיף מרווח פנימי של התוצאה לפני החתימה בפועל.
- התוסף שולח חזרה את החתימה לדפדפן באמצעות השיטה
reportSignature()
. אם לא ניתן לחשב את החתימה, יש להפעיל את השיטה ללא חתימה. - אם החתימה סופקה, הדפדפן ישלים את לחיצת היד בפרוטוקול TLS.
רצף השלבים בפועל עשוי להיות שונה. לדוגמה, אם נעשה שימוש באישור אוטומטי לפי מדיניות הארגון (יש לעיין בAutoSelectCertificateForUrls
ובמדיניות Chrome למשתמשים), המשתמש לא יתבקש לבחור אישור.
בתוסף, הקוד יכול להיראות דומה לקטע הקוד הבא:
function collectAvailableCertificates() {
// Return all certificates that this Extension can currently provide.
// For example:
return [{
certificateChain: [new Uint8Array(...)],
supportedAlgorithms: ['RSASSA_PKCS1_v1_5_SHA256']
}];
}
// The Extension calls this function every time the currently available list of
// certificates changes, and also once after the Extension's initialization.
function onAvailableCertificatesChanged() {
chrome.certificateProvider.setCertificates({
clientCertificates: collectAvailableCertificates()
});
}
function handleCertificatesUpdateRequest(request) {
// Report the currently available certificates as a response to the request
// event. This is important for supporting the case when the Extension is
// unable to detect the changes proactively.
chrome.certificateProvider.setCertificates({
certificatesRequestId: request.certificatesRequestId,
clientCertificates: collectAvailableCertificates()
});
}
// Returns a private key handle for the given DER-encoded certificate.
// |certificate| is an ArrayBuffer.
function getPrivateKeyHandle(certificate) {...}
// Digests and signs |input| with the given private key. |input| is an
// ArrayBuffer. |algorithm| is an Algorithm.
// Returns the signature as ArrayBuffer.
function signUnhashedData(privateKey, input, algorithm) {...}
function handleSignatureRequest(request) {
// Look up the handle to the private key of |request.certificate|.
const key = getPrivateKeyHandle(request.certificate);
if (!key) {
// Handle if the key isn't available.
console.error('Key for requested certificate no available.');
// Abort the request by reporting the error to the API.
chrome.certificateProvider.reportSignature({
signRequestId: request.signRequestId,
error: 'GENERAL_ERROR'
});
return;
}
const signature = signUnhashedData(key, request.input, request.algorithm);
chrome.certificateProvider.reportSignature({
signRequestId: request.signRequestId,
signature: signature
});
}
chrome.certificateProvider.onCertificatesUpdateRequested.addListener(
handleCertificatesUpdateRequest);
chrome.certificateProvider.onSignatureRequested.addListener(
handleSignatureRequest);
סוגים
Algorithm
סוגים של אלגוריתמים נתמכים לחתימה קריפטוגרפית.
טיפוסים בני מנייה (enum)
"RSASSA_PKCS1_v1_5_MD5_SHA1"
מפרט את אלגוריתם החתימה RSASSA PKCS#1 v1.5 עם Hashing MD5-SHA-1. התוסף לא יכול לצרף קידומת DigestInfo, אלא רק להוסיף מרווח פנימי של PKCS#1. האלגוריתם הזה הוצא משימוש והחל מגרסה 109 לא יוצגו בקשות מ-Chrome.
"RSASSA_PKCS1_v1_5_SHA1"
ההגדרה קובעת את אלגוריתם החתימה RSASSA PKCS#1 v1.5 עם פונקציית הגיבוב SHA-1.
"RSASSA_PKCS1_v1_5_SHA256"
מפרט את אלגוריתם החתימה RSASSA PKCS#1 v1.5 עם פונקציית הגיבוב SHA-256.
"RSASSA_PKCS1_v1_5_SHA384"
ההגדרה קובעת את אלגוריתם החתימה RSASSA PKCS#1 v1.5 עם פונקציית הגיבוב SHA-384.
"RSASSA_PKCS1_v1_5_SHA512"
מפרט את אלגוריתם החתימה RSASSA PKCS#1 v1.5 עם פונקציית הגיבוב SHA-512.
'RSASSA_PSS_SHA256'
ההגדרה קובעת את אלגוריתם החתימה RSASSA PSS עם פונקציית הגיבוב (hashing) SHA-256, פונקציית היצירה של מסכת MGF1 ו-salt באותו גודל כמו הגיבוב.
'RSASSA_PSS_SHA384'
ההגדרה קובעת את אלגוריתם החתימה RSASSA PSS עם פונקציית הגיבוב (hashing) SHA-384, פונקציית היצירה של מסכת MGF1 ו-salt באותו גודל כמו הגיבוב.
'RSASSA_PSS_SHA512'
ההגדרה קובעת את אלגוריתם החתימה RSASSA PSS עם פונקציית הגיבוב (hashing) SHA-512, פונקציית היצירה של מסכת MGF1 ו-salt באותו גודל כמו הגיבוב.
CertificateInfo
תכונות
-
אישור
ArrayBuffer
חייב להיות בקידוד DER של אישור X.509. בשלב זה, יש תמיכה רק באישורים של מפתחות RSA.
-
supportedHashes
גיבוב[]
יש להגדיר את הערך לכל הגיבובים שנתמכים באישור הזה. המערכת תבקש מהתוסף הזה רק לשלוח חתימות של תקצירים שמחושבים באמצעות אחד מהאלגוריתמים האלה של גיבוב. צריך לעשות את זה בסדר שבו צריך להקטין את העדפת הגיבוב.
CertificatesUpdateRequest
תכונות
-
certificatesRequestId
number
מזהה הבקשה יועבר אל
setCertificates
.
ClientCertificateInfo
תכונות
-
certificateChain
ArrayBuffer[]
המערך חייב להכיל את קידוד DER של אישור הלקוח X.509 בתור הרכיב הראשון שלו.
האישור צריך לכלול רק אישור אחד.
-
supportedAlgorithms
אלגוריתם[]
כל האלגוריתמים שנתמכים באישור הזה. המערכת תבקש מהתוסף חתימות רק באמצעות אחד מהאלגוריתמים האלה.
Error
סוגי השגיאות שהתוסף יכול לדווח עליהן.
ערך
"GENERAL_ERROR"
Hash
הוּצא משימוש. הוחלף על ידי Algorithm
.
טיפוסים בני מנייה (enum)
"MD5_SHA1"
קביעת אלגוריתמים גיבוב (hashing) MD5 ו-SHA1.
"SHA1"
קביעת אלגוריתם הגיבוב SHA1.
"SHA256"
קביעת אלגוריתם הגיבוב SHA256.
"SHA384"
קביעת אלגוריתם הגיבוב SHA384.
"SHA512"
קביעת אלגוריתם הגיבוב SHA512.
PinRequestErrorType
סוגי השגיאות שיכולים להיות מוצגים למשתמש באמצעות הפונקציה requestPin.
טיפוסים בני מנייה (enum)
"INVALID_PIN"
מציין שקוד האימות לא חוקי.
"INVALID_PUK"
מציין שה-PUK לא חוקי.
"MAX_ATTEMPTS_EXCEEDED"
מציין את מספר הניסיון המקסימלי.
"UNKNOWN_ERROR"
מציין שהשגיאה לא יכולה להיות מיוצגת על ידי הסוגים שלמעלה.
PinRequestType
סוג הקוד שהתוסף מבקש עם הפונקציה requestPin.
טיפוסים בני מנייה (enum)
"קוד אימות"
מציין שהקוד המבוקש הוא קוד אימות.
'PUK'
הקוד המבוקש הוא PUK.
PinResponseDetails
תכונות
-
userInput
מחרוזת אופציונלי
הקוד שהמשתמש סיפק. השדה ריק אם המשתמש סגר את תיבת הדו-שיח או אם אירעה שגיאה אחרת.
ReportSignatureDetails
תכונות
-
error
אופציונלי
אירעה שגיאה במהלך יצירת החתימה, אם יש כזו.
-
signRequestId
number
מזהה הבקשה שהתקבל דרך האירוע
onSignatureRequested
. -
signature
ArrayBuffer אופציונלי
החתימה, אם היא נוצרה בהצלחה.
RequestPinDetails
תכונות
-
attemptsLeft
מספר אופציונלי
מספר הניסיונות שנותרו. האימות מתבצע כדי שכל ממשק משתמש יוכל להציג את המידע הזה למשתמש. לא צפוי ש-Chrome יאכוף זאת. במקום זאת, התוסף צריך להפעיל את stopPinRequest עם errorType = MAX_TryS_EXCEEDED כאשר יש חריגה ממספר בקשות ה-PIN.
-
errorType
PinRequestErrorType אופציונלי
תבנית השגיאה שמוצגת למשתמש. צריך להגדיר את האפשרות הזו אם הבקשה הקודמת נכשלה, כדי ליידע את המשתמש על סיבת הכשל.
-
requestType
PinRequestType אופציונלי
סוג הקוד המבוקש. ברירת המחדל היא קוד אימות.
-
signRequestId
number
המזהה שסופק על ידי Chrome ב-SignRequest.
SetCertificatesDetails
תכונות
-
certificatesRequestId
מספר אופציונלי
כשמתבצעת קריאה בתגובה ל-
onCertificatesUpdateRequested
, הוא צריך להכיל את הערךcertificatesRequestId
שהתקבל. אחרת, צריך לבטל את ההגדרה. -
clientCertificates
רשימה של אישורי הלקוח שזמינים כרגע.
-
error
אופציונלי
אירעה שגיאה במהלך חילוץ האישורים, אם יש כאלה. במקרים המתאימים תוצג למשתמשים השגיאה הזאת.
SignatureRequest
תכונות
-
אלגוריתם
אלגוריתם החתימה שבו יש להשתמש.
-
אישור
ArrayBuffer
קידוד DER של אישור X.509. התוסף צריך לחתום על
input
באמצעות המפתח הפרטי המשויך. -
קלט
ArrayBuffer
נתונים לחתימה. שימו לב שהנתונים לא מגובבים.
-
signRequestId
number
מזהה הבקשה יועבר אל
reportSignature
.
SignRequest
תכונות
-
אישור
ArrayBuffer
קידוד DER של אישור X.509. התוסף צריך לחתום על
digest
באמצעות המפתח הפרטי המשויך. -
תקציר (digest)
ArrayBuffer
התקציר שחייב להיות חתום.
-
hash
מתייחס לאלגוריתם הגיבוב ששימש ליצירת
digest
. -
signRequestId
number
Chrome 57 ומעלההמזהה הייחודי שבו התוסף צריך להשתמש אם יש צורך להפעיל שיטה אחרת, לדוגמה requestPin.
StopPinRequestDetails
תכונות
-
errorType
PinRequestErrorType אופציונלי
תבנית השגיאה. אם הוא קיים, הוא יוצג למשתמש. נועדה לכלול את הסיבה לעצירת התהליך אם היא נגרמה עקב שגיאה, למשל MAX_TryS_EXCEEDED.
-
signRequestId
number
המזהה שסופק על ידי Chrome ב-SignRequest.
שיטות
reportSignature()
chrome.certificateProvider.reportSignature(
details: ReportSignatureDetails,
callback?: function,
)
יש לקרוא את המענה כתשובה ל-onSignatureRequested
.
בסופו של דבר התוסף צריך להפעיל את הפונקציה הזו עבור כל אירוע onSignatureRequested
. אחרי זמן מה, הטמעת ה-API תפסיק להמתין לקריאה הזו, וכשהפונקציה תפעל עם הודעת שגיאה של זמן קצוב לתפוגה.
פרמטרים
-
פרטים
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:() => void
החזרות
-
Promise<void>
Chrome 96 ומעלהיש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.
requestPin()
chrome.certificateProvider.requestPin(
details: RequestPinDetails,
callback?: function,
)
המערכת מבקשת מהמשתמש את קוד האימות. מותר לשלוח רק בקשה מתמשכת אחת בכל פעם. הבקשות שנשלחות בזמן תהליך אחר נדחות. אם יש תהליך אחר בעיצומו, באחריות התוסף לנסות שוב מאוחר יותר.
פרמטרים
-
פרטים
מכילה את הפרטים על תיבת הדו-שיח המבוקשת.
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:(details?: PinResponseDetails) => void
-
פרטים
PinResponseDetails אופציונלי
-
החזרות
-
Promise<PinResponseDetails | undefined>
Chrome 96 ומעלהיש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.
setCertificates()
chrome.certificateProvider.setCertificates(
details: SetCertificatesDetails,
callback?: function,
)
מגדיר רשימה של אישורים לשימוש בדפדפן.
התוסף צריך לקרוא לפונקציה הזו לאחר האתחול ובכל שינוי בקבוצת האישורים הזמינים כעת. בנוסף, התוסף צריך לקרוא לפונקציה הזו בתגובה ל-onCertificatesUpdateRequested
בכל פעם שהאירוע הזה מתקבל.
פרמטרים
-
פרטים
האישורים להגדרה. המערכת תתעלם מאישורים לא חוקיים.
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:() => void
החזרות
-
Promise<void>
Chrome 96 ומעלהיש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.
stopPinRequest()
chrome.certificateProvider.stopPinRequest(
details: StopPinRequestDetails,
callback?: function,
)
עוצרת את בקשת ה-PIN שהופעלה על ידי הפונקציה requestPin
.
פרמטרים
-
פרטים
מכילה את הפרטים על הסיבה להפסקת תהליך הבקשה.
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:() => void
החזרות
-
Promise<void>
Chrome 96 ומעלהיש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.
אירועים
onCertificatesRequested
chrome.certificateProvider.onCertificatesRequested.addListener(
callback: function,
)
במקומו צריך להשתמש ב-onCertificatesUpdateRequested
.
האירוע הזה מופעל בכל פעם שהדפדפן מבקש את רשימת האישורים הנוכחית שהתוסף הזה מספק. התוסף צריך להפעיל את reportCallback
פעם אחת בלבד עם רשימת האישורים הנוכחית.
פרמטרים
-
קריאה חוזרת (callback)
פונקציה
הפרמטר
callback
נראה כך:(reportCallback: function) => void
-
reportCallback
פונקציה
הפרמטר
reportCallback
נראה כך:(certificates: CertificateInfo[], callback: function) => void
-
אישורים
-
קריאה חוזרת (callback)
פונקציה
הפרמטר
callback
נראה כך:(rejectedCertificates: ArrayBuffer[]) => void
-
rejectedCertificates
ArrayBuffer[]
-
-
-
onCertificatesUpdateRequested
chrome.certificateProvider.onCertificatesUpdateRequested.addListener(
callback: function,
)
האירוע הזה מופעל אם האישורים שהוגדרו דרך setCertificates
לא מספיקים או אם הדפדפן מבקש מידע מעודכן. לתוסף צריכה להיות קריאה ל-setCertificates
עם רשימת האישורים המעודכנת והמזהה certificatesRequestId
שהתקבל.
פרמטרים
-
קריאה חוזרת (callback)
פונקציה
הפרמטר
callback
נראה כך:(request: CertificatesUpdateRequest) => void
onSignatureRequested
chrome.certificateProvider.onSignatureRequested.addListener(
callback: function,
)
האירוע הזה מופעל בכל פעם שהדפדפן צריך לחתום על הודעה באמצעות אישור שהתוסף הזה סיפק דרך setCertificates
.
התוסף חייב לחתום על נתוני הקלט מ-request
באמצעות האלגוריתם והמפתח הפרטי המתאימים, ולהחזיר אותם באמצעות קריאה ל-reportSignature
עם signRequestId
שהתקבל.
פרמטרים
-
קריאה חוזרת (callback)
פונקציה
הפרמטר
callback
נראה כך:(request: SignatureRequest) => void
-
בקשה
-
onSignDigestRequested
chrome.certificateProvider.onSignDigestRequested.addListener(
callback: function,
)
במקומו צריך להשתמש ב-onSignatureRequested
.
האירוע הזה מופעל בכל פעם שהדפדפן צריך לחתום על הודעה באמצעות אישור שהתוסף הזה סיפק בתגובה לאירוע onCertificatesRequested
. התוסף חייב לחתום על הנתונים ב-request
באמצעות האלגוריתם המתאים והמפתח הפרטי המתאים ולהחזיר אותם באמצעות קריאה ל-reportCallback
. חובה להפעיל את reportCallback
פעם אחת בלבד.
פרמטרים
-
קריאה חוזרת (callback)
פונקציה
הפרמטר
callback
נראה כך:(request: SignRequest, reportCallback: function) => void
-
בקשה
-
reportCallback
פונקציה
Chrome מגרסה 47 ואילךהפרמטר
reportCallback
נראה כך:(signature?: ArrayBuffer) => void
-
signature
ArrayBuffer אופציונלי
-
-