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. האלגוריתם הזה הוצא משימוש, ומערכת Chrome לעולם לא תבקש אותו החל מגרסה 109.

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

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

CertificatesUpdateRequest

גרסה 86 ואילך של Chrome

מאפיינים

  • certificatesRequestId

    number

    מזהה הבקשה שיוענק ל-setCertificates.

ClientCertificateInfo

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

מאפיינים

  • certificateChain

    ArrayBuffer[]

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

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

  • supportedAlgorithms

    Algorithm[]

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

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

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

  • signRequestId

    number

    המזהה ש-Chrome מספק ב-SignRequest.

SetCertificatesDetails

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

מאפיינים

  • certificatesRequestId

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

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

  • 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

    גיבוב

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

צריך להפעיל את הפונקציה הזו בתגובה להפעלה של onSignatureRequested.

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

פרמטרים

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

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

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

    () => void

החזרות

  • Promise<void>

    גרסה 96 ואילך של Chrome

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

requestPin()

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

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

פרמטרים

  • פרטים

    RequestPinDetails

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

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

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

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

    (details?: PinResponseDetails) => void

החזרות

  • Promise<PinResponseDetails | undefined>

    גרסה 96 ואילך של Chrome

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

setCertificates()

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

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

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

פרמטרים

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

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

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

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

    () => void

החזרות

  • Promise<void>

    גרסה 96 ואילך של Chrome

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

stopPinRequest()

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

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

פרמטרים

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

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

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

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

    () => void

החזרות

  • Promise<void>

    גרסה 96 ואילך של Chrome

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

אירועים

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