chrome.certificateProvider

refresh date: 2026-09-25 robots: noindex

תיאור

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

הרשאות

certificateProvider

זמינות

Chrome 46 ואילך 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() {
  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 ואילך

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

טיפוסים בני מנייה (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 ואילך

מאפיינים

  • 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 כשמספר בקשות ה-PIN חורג מהמגבלה.

  • errorType

    PinRequestErrorType אופציונלי

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

  • requestType

    ‫PinRequestType אופציונלי

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

  • signRequestId

    number

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

SetCertificatesDetails

‫Chrome מגרסה 86 ואילך

מאפיינים

  • certificatesRequestId

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

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

  • 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

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

  • מתייחס לאלגוריתם הגיבוב ששימש ליצירת 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

    function optional

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

    () => void

החזרות

  • Promise<void>

    ‫Chrome מגרסה 96 ואילך

    הבטחות נתמכות רק ב-Manifest V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callbacks).

requestPin()

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

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

פרמטרים

החזרות

  • Promise<PinResponseDetails | undefined>

    ‫Chrome מגרסה 96 ואילך

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

    הבטחות נתמכות רק ב-Manifest V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callbacks).

setCertificates()

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

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

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

פרמטרים

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

  • callback

    function optional

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

    () => void

החזרות

  • Promise<void>

    ‫Chrome מגרסה 96 ואילך

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

    הבטחות נתמכות רק ב-Manifest V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callbacks).

stopPinRequest()

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

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

פרמטרים

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

  • callback

    function optional

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

    () => void

החזרות

  • Promise<void>

    ‫Chrome מגרסה 96 ואילך

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

    הבטחות נתמכות רק ב-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 אופציונלי