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

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

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

טיפוסים בני מנייה (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[]

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

CertificatesUpdateRequest

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

מאפיינים

  • certificatesRequestId

    number

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

ClientCertificateInfo

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

מאפיינים

  • certificateChain

    ArrayBuffer[]

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

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

  • supportedAlgorithms

    Algorithm[]

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

Error

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

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

ערך

"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

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

מאפיינים

  • 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

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

מאפיינים

  • certificatesRequestId

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

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

  • clientCertificates

    ClientCertificateInfo[]

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

  • error

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

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

SignatureRequest

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

מאפיינים

  • אלגוריתם

    אלגוריתם

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

  • אישור

    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.

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.

setCertificates()

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

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

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

פרמטרים

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

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

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

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

    () => void

החזרות

  • Promise<void>

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

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

stopPinRequest()

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

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

פרמטרים

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

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

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

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

    () => void

החזרות

  • Promise<void>

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

    יש תמיכה ב-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

גרסה 86 ואילך של Chrome 
chrome.certificateProvider.onCertificatesUpdateRequested.addListener(
  callback: function,
)

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

פרמטרים

onSignatureRequested

גרסה 86 ואילך של Chrome 
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 אופציונלי