chrome.certificateProvider

תיאור

אפשר להשתמש ב-API הזה כדי לחשוף אישורים לפלטפורמה, והפלטפורמה יכולה להשתמש באישורים האלה לאימות TLS.

הרשאות

certificateProvider

זמינות

‫Chrome 46 ואילך ChromeOS בלבד

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

שימוש אופייני ב-API הזה כדי לחשוף אישורי לקוח ל-ChromeOS מתבצע באופן הבא:

  • התוסף נרשם לאירועים onCertificatesUpdateRequested ו-onSignatureRequested.
  • התוסף קורא ל-setCertificates() כדי לספק את הרשימה הראשונית של האישורים אחרי האתחול.
  • התוסף עוקב אחרי השינויים ברשימת האישורים הזמינים ומפעיל את setCertificates() כדי להודיע לדפדפן על כל שינוי כזה.
  • במהלך לחיצת היד של TLS, הדפדפן מקבל בקשה לאישור לקוח. באירוע onCertificatesUpdateRequested, הדפדפן מבקש מהתוסף לדווח על כל האישורים שהוא מספק כרגע.
  • התוסף מחזיר את האישורים שזמינים כרגע באמצעות השיטה setCertificates().
  • הדפדפן משווה בין כל האישורים הזמינים לבין בקשת אישור הלקוח מהמארח המרוחק. ההתאמות מוצגות למשתמש בתיבת דו-שיח לבחירה.
  • המשתמש יכול לבחור אישור ובכך לאשר את האימות או לבטל אותו.
תיבת דו-שיח לבחירת אישור
תיבת דו-שיח לבחירת אישור.
  • אם המשתמש מבטל את האימות או אם אין אישור שתואם לבקשה, אימות לקוח ה-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

‫Chrome 86 ואילך

סוגים של אלגוריתמים קריפטוגרפיים לחתימה שנתמכים.

Enum

‫"RSASSA_PKCS1_v1_5_MD5_SHA1"
מציין את אלגוריתם החתימה RSASSA PKCS#1 v1.5 עם הגיבוב 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 עם פונקציית הגיבוב SHA-256, פונקציית יצירת המסכה MGF1 והמלח באותו גודל כמו הגיבוב.

‫RSASSA_PSS_SHA384
מציין את אלגוריתם החתימה RSASSA PSS עם פונקציית הגיבוב SHA-384, פונקציית יצירת המסכה MGF1 והמלח באותו גודל כמו הגיבוב.

‫RSASSA_PSS_SHA512
מציין את אלגוריתם החתימה RSASSA PSS עם פונקציית הגיבוב SHA-512, פונקציית יצירת המסכה MGF1 והמלח באותו גודל כמו הגיבוב.

CertificateInfo

מאפיינים

  • אישור

    ArrayBuffer

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

  • supportedHashes

    ‫Hash[]

    הערך צריך להיות מוגדר לכל הגיבובים שנתמכים באישור הזה. התוסף הזה יבקש חתימות רק על תמציות (digest) שחושבו באמצעות אחד מאלגוריתמי הגיבוב האלה. הסדר צריך להיות לפי העדפה יורדת של הגיבוב.

CertificatesUpdateRequest

‫Chrome 86 ואילך

מאפיינים

  • certificatesRequestId

    number

    מזהה הבקשה שיועבר אל setCertificates.

ClientCertificateInfo

‫Chrome 86 ואילך

מאפיינים

  • certificateChain

    ArrayBuffer[]

    הרכיב הראשון במערך צריך להיות קידוד DER של אישור הלקוח X.509.

    הוא חייב לכלול אישור אחד בלבד.

  • supportedAlgorithms

    אלגוריתם[]

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

Error

‫Chrome 86 ואילך

סוגי השגיאות שהתוסף יכול לדווח עליהן.

ערך

‫"GENERAL_ERROR"

Hash

הוצא משימוש. הוחלף על ידי Algorithm.

Enum

‫"MD5_SHA1"
מציין את אלגוריתמי הגיבוב MD5 ו-SHA1.

‫"SHA1"
מציין את אלגוריתם הגיבוב SHA1.

‫"SHA256"
מציין את אלגוריתם הגיבוב SHA256.

‫‎"SHA384"‎
מציין את אלגוריתם הגיבוב SHA384.

‫'SHA512'
מציין את אלגוריתם הגיבוב SHA512.

PinRequestErrorType

‫Chrome 57 ואילך

סוגי השגיאות שיכולים להיות מוצגים למשתמש דרך הפונקציה requestPin.

Enum

‫INVALID_PIN
מציין שקוד האימות לא תקין.

‫INVALID_PUK
מציין שה-PUK לא תקין.

‫"MAX_ATTEMPTS_EXCEEDED"
מציין שחרגתם ממספר הניסיונות המקסימלי.

‫"UNKNOWN_ERROR"
מציין שלא ניתן לייצג את השגיאה באמצעות הסוגים שלמעלה.

PinRequestType

‫Chrome 57 ואילך

סוג הקוד שהתוסף מבקש באמצעות הפונקציה requestPin.

Enum

‫"PIN"
מציין שהקוד המבוקש הוא קוד אימות.

‫PUK
מציין שהקוד המבוקש הוא קוד PUK.

PinResponseDetails

‫Chrome 57 ואילך

מאפיינים

  • userInput

    מחרוזת אופציונלי

    הקוד שסיפק המשתמש. הערך ריק אם המשתמש סגר את תיבת הדו-שיח או אם אירעה שגיאה אחרת.

ReportSignatureDetails

‫Chrome 86 ואילך

מאפיינים

  • error

    ‫"GENERAL_ERROR"
     אופציונלי

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

  • signRequestId

    number

    מזהה הבקשה שהתקבל דרך האירוע onSignatureRequested.

  • signature

    ‫ArrayBuffer אופציונלי

    החתימה, אם היא נוצרה בהצלחה.

RequestPinDetails

‫Chrome 57 ואילך

מאפיינים

  • attemptsLeft

    מספר אופציונלי

    מספר הניסיונות שנותרו. המידע הזה מסופק כדי שכל ממשק משתמש יוכל להציג אותו למשתמש. לא צפוי ש-Chrome יאכוף את זה. במקום זאת, התוסף צריך לקרוא ל-stopPinRequest עם errorType = MAX_ATTEMPTS_EXCEEDED כשהמספר של בקשות קוד האימות חורג מהמותר.

  • errorType

    ‫PinRequestErrorType אופציונלי

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

  • requestType

    ‫PinRequestType אופציונלי

    סוג הקוד המבוקש. ברירת המחדל היא PIN.

  • signRequestId

    number

    המזהה שניתן על ידי Chrome ב-SignRequest.

SetCertificatesDetails

‫Chrome 86 ואילך

מאפיינים

  • certificatesRequestId

    מספר אופציונלי

    כשמפעילים את הפונקציה בתגובה ל-onCertificatesUpdateRequested, היא צריכה להכיל את הערך certificatesRequestId שהתקבל. אחרת, צריך להגדיר את הערך כ-unset.

  • clientCertificates

    ClientCertificateInfo[]

    רשימה של אישורי לקוח שזמינים כרגע.

  • error

    ‫"GENERAL_ERROR"
     אופציונלי

    שגיאה שאירעה במהלך חילוץ האישורים, אם יש. השגיאה הזו תוצג למשתמש כשצריך.

SignatureRequest

‫Chrome 86 ואילך

מאפיינים

  • אלגוריתם

    אלגוריתם

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

  • אישור

    ArrayBuffer

    קידוד DER של אישור X.509. התוסף צריך לחתום על input באמצעות המפתח הפרטי המשויך.

  • קלט

    ArrayBuffer

    הנתונים שצריך לחתום עליהם. חשוב לזכור שהנתונים לא מגובבים.

  • signRequestId

    number

    מזהה הבקשה שיועבר אל reportSignature.

SignRequest

מאפיינים

  • אישור

    ArrayBuffer

    קידוד DER של אישור X.509. התוסף צריך לחתום על digest באמצעות המפתח הפרטי המשויך.

  • תקציר (digest)

    ArrayBuffer

    התקציר שצריך לחתום עליו.

  • hash

    Hash

    מפנה לאלגוריתם הגיבוב ששימש ליצירת digest.

  • signRequestId

    number

    ‫Chrome 57 ואילך

    המזהה הייחודי שבו התוסף צריך להשתמש אם הוא צריך להפעיל method שדורשת אותו, למשל requestPin.

StopPinRequestDetails

‫Chrome 57 ואילך

מאפיינים

  • errorType

    ‫PinRequestErrorType אופציונלי

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

  • signRequestId

    number

    המזהה שניתן על ידי Chrome ב-SignRequest.

Methods

reportSignature()

‫Chrome 86 ואילך 
chrome.certificateProvider.reportSignature(
  details: ReportSignatureDetails,
): Promise<void>

צריך להתקשר בתגובה לonSignatureRequested.

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

פרמטרים

החזרות

  • Promise<void>

    ‫Chrome 96 ואילך

requestPin()

‫Chrome 57 ואילך 
chrome.certificateProvider.requestPin(
  details: RequestPinDetails,
): Promise<PinResponseDetails | undefined>

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

פרמטרים

  • פרטים

    RequestPinDetails

    מכיל את הפרטים של תיבת הדו-שיח המבוקשת.

החזרות

setCertificates()

‫Chrome 86 ואילך 
chrome.certificateProvider.setCertificates(
  details: SetCertificatesDetails,
): Promise<void>

מגדירה רשימה של אישורים לשימוש בדפדפן.

התוסף צריך לקרוא לפונקציה הזו אחרי האתחול, וגם בכל שינוי במערך האישורים שזמינים כרגע. בנוסף, התוסף צריך לקרוא לפונקציה הזו בתגובה ל-onCertificatesUpdateRequested בכל פעם שהאירוע הזה מתקבל.

פרמטרים

  • האישורים להגדרה. המערכת תתעלם מאישורים לא תקינים.

החזרות

  • Promise<void>

    ‫Chrome 96 ואילך

stopPinRequest()

‫Chrome 57 ואילך 
chrome.certificateProvider.stopPinRequest(
  details: StopPinRequestDetails,
): Promise<void>

עוצר את בקשת ה-PIN שהופעלה על ידי הפונקציה requestPin.

פרמטרים

החזרות

  • Promise<void>

    ‫Chrome 96 ואילך

אירועים

onCertificatesUpdateRequested

‫Chrome 86 ואילך 
chrome.certificateProvider.onCertificatesUpdateRequested.addListener(
  callback: function,
)

האירוע הזה מופעל אם האישורים שהוגדרו באמצעות setCertificates לא מספיקים או אם הדפדפן מבקש מידע מעודכן. התוסף צריך לקרוא ל-setCertificates עם רשימת האישורים המעודכנת ועם certificatesRequestId שהתקבל.

פרמטרים

onSignatureRequested

‫Chrome 86 ואילך 
chrome.certificateProvider.onSignatureRequested.addListener(
  callback: function,
)

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

התוסף צריך לחתום על נתוני הקלט מ-request באמצעות האלגוריתם המתאים והמפתח הפרטי, ולהחזיר אותם על ידי קריאה ל-reportSignature עם signRequestId שהתקבל.

פרמטרים