browser.certificateProvider

תיאור

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

הרשאות

certificateProvider

זמינות

‫Chrome 46 ואילך ‫browser.* ‎ מגרסה 148 של Chrome ‫ChromeOS בלבד

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

כדי לחשוף אישורי לקוח ל-ChromeOS, בדרך כלל משתמשים ב-API הזה באופן הבא:

  • התוסף נרשם לאירועים 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() {
  browser.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.
  browser.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.
    browser.certificateProvider.reportSignature({
      signRequestId: request.signRequestId,
      error: 'GENERAL_ERROR'
    });
    return;
  }

  const signature = signUnhashedData(key, request.input, request.algorithm);
  browser.certificateProvider.reportSignature({
    signRequestId: request.signRequestId,
    signature: signature
  });
}

browser.certificateProvider.onCertificatesUpdateRequested.addListener(
    handleCertificatesUpdateRequest);
browser.certificateProvider.onSignatureRequested.addListener(
    handleSignatureRequest);

סוגים

Algorithm

‫Chrome 86 ואילך ‫browser.* ‎ מגרסה Chrome 148

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

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

"RSASSA_PKCS1_v1_5_MD5_SHA1"
מציין את אלגוריתם החתימה RSASSA PKCS#1 v1.5 עם גיבוב MD5-SHA-1. התוסף לא יכול להוסיף קידומת DigestInfo, אלא רק ריפוד PKCS#1. האלגוריתם הזה הוצא משימוש, ו-Chrome לא יבקש אותו יותר החל מגרסה 109.

‫"RSASSA_PKCS1_v1_5_SHA1"
מציין את אלגוריתם החתימה RSASSA PKCS#1 v1.5 עם פונקציית הגיבוב (hash) ‏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 וה-salt באותו גודל כמו הגיבוב.

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

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

CertificateInfo

מאפיינים

  • אישור

    ArrayBuffer

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

  • supportedHashes

    גיבוב[]

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

CertificatesUpdateRequest

‫Chrome 86 ואילך ‫browser.* ‎ מגרסה Chrome 148

מאפיינים

  • certificatesRequestId

    number

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

ClientCertificateInfo

‫Chrome 86 ואילך ‫browser.* ‎ מגרסה Chrome 148

מאפיינים

  • certificateChain

    ArrayBuffer[]‎

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

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

  • supportedAlgorithms

    אלגוריתם[]

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

Error

‫Chrome 86 ואילך ‫browser.* ‎ מגרסה Chrome 148

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

ערך

"GENERAL_ERROR"

Hash

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

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

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

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

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

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

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

PinRequestErrorType

‫Chrome 57 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

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

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

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

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

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

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

PinRequestType

‫Chrome 57 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

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

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

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

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

PinResponseDetails

‫Chrome 57 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

מאפיינים

  • userInput

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

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

ReportSignatureDetails

‫Chrome 86 ואילך ‫browser.* ‎ מגרסה Chrome 148

מאפיינים

  • error

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

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

  • signRequestId

    number

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

  • signature

    ‫ArrayBuffer אופציונלי

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

RequestPinDetails

‫Chrome 57 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

מאפיינים

  • attemptsLeft

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

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

  • errorType

    PinRequestErrorType אופציונלי

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

  • requestType

    ‫PinRequestType אופציונלי

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

  • signRequestId

    number

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

SetCertificatesDetails

‫Chrome 86 ואילך ‫browser.* ‎ מגרסה Chrome 148

מאפיינים

  • certificatesRequestId

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

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

  • clientCertificates

    ClientCertificateInfo[]

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

  • error

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

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

SignatureRequest

‫Chrome 86 ואילך ‫browser.* ‎ מגרסה Chrome 148

מאפיינים

  • אלגוריתם

    אלגוריתם

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

  • אישור

    ArrayBuffer

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

  • קלט

    ArrayBuffer

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

  • signRequestId

    number

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

SignRequest

מאפיינים

  • אישור

    ArrayBuffer

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

  • תקציר (digest)

    ArrayBuffer

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

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

  • signRequestId

    number

    ‫Chrome 57 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

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

StopPinRequestDetails

‫Chrome 57 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

מאפיינים

  • errorType

    PinRequestErrorType אופציונלי

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

  • signRequestId

    number

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

Methods

reportSignature()

‫Chrome 86 ואילך ‫browser.* ‎ מגרסה Chrome 148 
browser.certificateProvider.reportSignature(
  details: ReportSignatureDetails,
): Promise<void>

צריך להפעיל אותה בתגובה ל-onSignatureRequested.

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

פרמטרים

החזרות

  • Promise<void>

    ‫Chrome 96 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

requestPin()

‫Chrome 57 ואילך ‫browser.* ‎ מגרסה 148 של Chrome 
browser.certificateProvider.requestPin(
  details: RequestPinDetails,
): Promise<PinResponseDetails | undefined>

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

פרמטרים

  • פרטים

    RequestPinDetails

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

החזרות

  • Promise<PinResponseDetails | undefined>

    ‫Chrome 96 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

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

setCertificates()

‫Chrome 86 ואילך ‫browser.* ‎ מגרסה Chrome 148 
browser.certificateProvider.setCertificates(
  details: SetCertificatesDetails,
): Promise<void>

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

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

פרמטרים

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

החזרות

  • Promise<void>

    ‫Chrome 96 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

    הפונקציה מחזירה Promise שמטופל בסיום.

stopPinRequest()

‫Chrome 57 ואילך ‫browser.* ‎ מגרסה 148 של Chrome 
browser.certificateProvider.stopPinRequest(
  details: StopPinRequestDetails,
): Promise<void>

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

פרמטרים

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

החזרות

  • Promise<void>

    ‫Chrome 96 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

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

אירועים

onCertificatesUpdateRequested

‫Chrome 86 ואילך ‫browser.* ‎ מגרסה Chrome 148 
browser.certificateProvider.onCertificatesUpdateRequested.addListener(
  callback: function,
)

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

פרמטרים

onSignatureRequested

‫Chrome 86 ואילך ‫browser.* ‎ מגרסה Chrome 148 
browser.certificateProvider.onSignatureRequested.addListener(
  callback: function,
)

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

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

פרמטרים