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 עם 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

Chrome 86 ומעלה

תכונות

  • certificatesRequestId

    מספר

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

ClientCertificateInfo

Chrome 86 ומעלה

תכונות

  • certificateChain

    ArrayBuffer[]

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

    האישור צריך לכלול רק אישור אחד.

  • supportedAlgorithms

    אלגוריתם[]

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

Error

Chrome 86 ומעלה

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

Value

"GENERAL_ERROR"

Hash

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

טיפוסים בני מנייה (enum)

"MD5_SHA1"
קביעת אלגוריתמים גיבוב (hashing) 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)

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

'PUK'
הקוד המבוקש הוא PUK.

PinResponseDetails

Chrome 57 ומעלה

תכונות

  • userInput

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

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

ReportSignatureDetails

Chrome 86 ומעלה

תכונות

  • error

     אופציונלי

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

  • signRequestId

    מספר

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

  • signature

    ArrayBuffer אופציונלי

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

RequestPinDetails

Chrome 57 ומעלה

תכונות

  • attemptsLeft

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

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

  • errorType

    PinRequestErrorType אופציונלי

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

  • requestType

    PinRequestType אופציונלי

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

  • signRequestId

    מספר

    המזהה שסופק על ידי Chrome ב-SignRequest.

SetCertificatesDetails

Chrome 86 ומעלה

תכונות

  • certificatesRequestId

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

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

  • clientCertificates

    ClientCertificateInfo[]

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

  • error

     אופציונלי

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

SignatureRequest

Chrome 86 ומעלה

תכונות

  • אלגוריתם

    אלגוריתם

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

  • אישור

    ArrayBuffer

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

  • קלט

    ArrayBuffer

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

  • signRequestId

    מספר

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

SignRequest

תכונות

  • אישור

    ArrayBuffer

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

  • תקציר (digest)

    ArrayBuffer

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

  • hash

    גיבוב

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

  • signRequestId

    מספר

    Chrome 57 ומעלה

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

StopPinRequestDetails

Chrome 57 ומעלה

תכונות

  • errorType

    PinRequestErrorType אופציונלי

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

  • signRequestId

    מספר

    המזהה שסופק על ידי Chrome ב-SignRequest.

שיטות

reportSignature()

Promise Chrome 86 ואילך 
chrome.certificateProvider.reportSignature(
  details: ReportSignatureDetails,
  callback?: function,
)

יש לקרוא את המענה כתשובה ל-onSignatureRequested.

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

פרמטרים

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

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

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

    ()=>void

החזרות

  • Promise<void>

    Chrome 96 ומעלה

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

requestPin()

Promise Chrome 57 ואילך 
chrome.certificateProvider.requestPin(
  details: RequestPinDetails,
  callback?: function,
)

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

פרמטרים

  • פרטים

    RequestPinDetails

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

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

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

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

    (details?: PinResponseDetails)=>void

החזרות

  • הבטחה<PinResponseDetails|undefined>

    Chrome 96 ומעלה

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

setCertificates()

Promise Chrome 86 ואילך 
chrome.certificateProvider.setCertificates(
  details: SetCertificatesDetails,
  callback?: function,
)

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

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

פרמטרים

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

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

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

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

    ()=>void

החזרות

  • Promise<void>

    Chrome 96 ומעלה

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

stopPinRequest()

Promise Chrome 57 ואילך 
chrome.certificateProvider.stopPinRequest(
  details: StopPinRequestDetails,
  callback?: function,
)

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

פרמטרים

  • מכילה את הפרטים על הסיבה להפסקת תהליך הבקשה.

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

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

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

    ()=>void

החזרות

  • Promise<void>

    Chrome 96 ומעלה

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

אירועים

onCertificatesRequested

Chrome 47 ואילך &leq; MV2 הוצא משימוש החל מגרסה 86 של Chrome
chrome.certificateProvider.onCertificatesRequested.addListener(
  callback: function,
)

במקומו צריך להשתמש ב-onCertificatesUpdateRequested.

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

פרמטרים

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

    פונקציה

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

    (reportCallback: function)=>void

    • reportCallback

      פונקציה

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

      (certificates: CertificateInfo[],callback: function)=>void

      • אישורים

        CertificateInfo[]

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

        פונקציה

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

        (rejectedCertificates: ArrayBuffer[])=>void

        • rejectedCertificates

          ArrayBuffer[]

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 שהתקבל.

פרמטרים

onSignDigestRequested

&leq; MV2 הוצא משימוש מאז Chrome 86
chrome.certificateProvider.onSignDigestRequested.addListener(
  callback: function,
)

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

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

פרמטרים

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

    פונקציה

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

    (request: SignRequest,reportCallback: function)=>void

    • בקשה

      SignRequest

    • reportCallback

      פונקציה

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

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

      (signature?: ArrayBuffer)=>void

      • signature

        ArrayBuffer אופציונלי