chrome.certificateProvider

תאריך הרענון: 2026-09-25 robots: noindex

תיאור

אפשר להשתמש ב-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 not 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 ואילך

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

ספירה

‫"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[]

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

CertificatesUpdateRequest

‫Chrome 86 ואילך

מאפיינים

  • certificatesRequestId

    number

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

ClientCertificateInfo

‫Chrome 86 ואילך

מאפיינים

  • certificateChain

    ArrayBuffer[]

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

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

  • supportedAlgorithms

    אלגוריתם[]

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

Error

‫Chrome 86 ואילך

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

ערך

‫"GENERAL_ERROR"

Hash

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

ספירה

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

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

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

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

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

PinRequestErrorType

‫Chrome 57 ואילך

סוגי השגיאות שיכולים להיות מוצגים למשתמש באמצעות הפונקציה requestPin.

ספירה

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

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

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

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

PinRequestType

‫Chrome 57 ואילך

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

ספירה

‫"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 אופציונלי

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

  • 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

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

  • signRequestId

    number

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

SignRequest

מאפיינים

  • אישור

    ArrayBuffer

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

  • תקציר (digest)

    ArrayBuffer

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

  • hash

    Hash

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

  • signRequestId

    number

    ‫Chrome 57 ואילך

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

StopPinRequestDetails

‫Chrome 57 ואילך

מאפיינים

  • errorType

    ‫PinRequestErrorType אופציונלי

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

  • signRequestId

    number

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

Methods

reportSignature()

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

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

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

פרמטרים

  • callback

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

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

    () => void

החזרות

  • Promise<void>

    ‫Chrome 96 ואילך

    התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

requestPin()

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

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

פרמטרים

  • פרטים

    RequestPinDetails

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

  • callback

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

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

    (details?: PinResponseDetails) => void

החזרות

  • Promise<PinResponseDetails | undefined>

    ‫Chrome 96 ואילך

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

    התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

setCertificates()

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

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

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

פרמטרים

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

  • callback

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

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

    () => void

החזרות

  • Promise<void>

    ‫Chrome 96 ואילך

    מחזירה Promise שמסתיים בסיום הפעולה.

    התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

stopPinRequest()

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

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

פרמטרים

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

  • callback

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

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

    () => void

החזרות

  • Promise<void>

    ‫Chrome 96 ואילך

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

    התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

אירועים

onCertificatesRequested

‫Chrome 47 ואילך ‫&leq; MV2 הוצא משימוש מאז Chrome 86
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 אופציונלי