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

"RSASSA_PKCS1_v1_5_SHA1"
המציין את אלגוריתם החתימה RSASSA PKCS#1 v1.5 עם פונקציית הגיבוב (hash) SHA-1.

"RSASSA_PKCS1_v1_5_SHA256"
המציין את אלגוריתם החתימה RSASSA PKCS#1 v1.5 עם פונקציית הגיבוב (hashing) SHA-256.

"RSASSA_PKCS1_v1_5_SHA384"
המציין את אלגוריתם החתימה RSASSA PKCS#1 v1.5 עם פונקציית הגיבוב (hashing) SHA-384.

"RSASSA_PKCS1_v1_5_SHA512"
המציין את אלגוריתם החתימה RSASSA PKCS#1 v1.5 עם פונקציית הגיבוב (hashing) SHA-512.

"RSASSA_PSS_SHA256"
ההגדרה קובעת את אלגוריתם החתימה RSASSA PSS עם פונקציית הגיבוב (hashing) SHA-256, פונקציית יצירת המסכה MGF1 ונתוני ה-salt שגודלם זהה לזה של הגיבוב.

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

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

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.

Enum

"MD5_SHA1"
הגדרת האלגוריתמים לגיבוב MD5 ו-SHA1.

"SHA1"
הציון הזה מציין את אלגוריתם הגיבוב (hashing) SHA1.

"SHA256"
הציון הזה מציין את אלגוריתם הגיבוב (hashing) SHA256.

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

"SHA512"
הציון הזה מציין את אלגוריתם הגיבוב (hashing) SHA512.

PinRequestErrorType

Chrome 57 ומעלה

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

Enum

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

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

"MAX_ATTEMPTS_EXCEEDED"
מציין את מספר הניסיונות המקסימלי.

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

PinRequestType

Chrome 57 ומעלה

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

Enum

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

"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 optional

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

  • 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

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

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

  • signRequestId

    number

    Chrome 57 ומעלה

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

StopPinRequestDetails

Chrome 57 ומעלה

מאפיינים

  • errorType

    PinRequestErrorType optional

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

  • signRequestId

    number

    המזהה שסופק על ידי Chrome ב-SignRequest.

שיטות

reportSignature()

הבטחה Chrome מגרסה 86 ואילך 
chrome.certificateProvider.reportSignature(
  details: ReportSignatureDetails,
  callback?: function,
)

צריכה להיקרא כתשובה ל-onSignatureRequested.

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

פרמטרים

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

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

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

    () => void

החזרות

  • הבטחה<Empty>

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

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

requestPin()

הבטחה Chrome 57 ואילך 
chrome.certificateProvider.requestPin(
  details: RequestPinDetails,
  callback?: function,
)

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

פרמטרים

  • פרטים

    RequestPinDetails

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

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

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

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

    (details?: PinResponseDetails) => void

החזרות

  • Promise&lt;PinResponseDetails | לא מוגדר>

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

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

setCertificates()

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

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

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

פרמטרים

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

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

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

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

    () => void

החזרות

  • הבטחה<Empty>

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

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

stopPinRequest()

הבטחה Chrome 57 ואילך 
chrome.certificateProvider.stopPinRequest(
  details: StopPinRequestDetails,
  callback?: function,
)

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

פרמטרים

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

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

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

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

    () => void

החזרות

  • הבטחה<Empty>

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

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

אירועים

onCertificatesRequested

Chrome 47 ואילך &amp;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

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