chrome.certificateProvider

توضیحات

از این API برای نمایش گواهینامه‌ها به پلتفرمی استفاده کنید که می‌تواند از این گواهینامه‌ها برای احراز هویت TLS استفاده کند.

مجوزها

certificateProvider

در دسترس بودن

فقط کروم او اس ۴۶+

کاربرد

استفاده معمول از این API برای نمایش گواهی‌های کلاینت به ChromeOS از این مراحل پیروی می‌کند:

  • این افزونه رویدادهای onCertificatesUpdateRequested و onSignatureRequested را ثبت می‌کند.
  • The Extension calls setCertificates to provide the initial list of certificates after the initialization.
  • این افزونه تغییرات در لیست گواهی‌های موجود را رصد می‌کند و setCertificates را فراخوانی می‌کند تا مرورگر را از هرگونه تغییری مطلع کند.
  • در طول یک TLS handshake، مرورگر یک درخواست گواهی کلاینت دریافت می‌کند. با رویداد onCertificatesUpdateRequested ، مرورگر از افزونه می‌خواهد که تمام گواهی‌هایی را که در حال حاضر ارائه می‌دهد، گزارش دهد.
  • افزونه با استفاده از متد setCertificates ، گواهی‌های موجود فعلی را گزارش می‌دهد.
  • مرورگر تمام گواهینامه‌های موجود را با درخواست گواهینامه کلاینت از میزبان راه دور مطابقت می‌دهد. موارد مطابقت در یک کادر محاوره‌ای انتخاب به کاربر نمایش داده می‌شود.
  • کاربر می‌تواند یک گواهی را انتخاب کند و از این طریق احراز هویت را تأیید یا لغو کند.

پنجره انتخاب گواهی

  • اگر کاربر احراز هویت را لغو کند یا هیچ گواهی با درخواست مطابقت نداشته باشد، احراز هویت کلاینت TLS لغو می‌شود.
  • در غیر این صورت، اگر کاربر احراز هویت را با گواهی ارائه شده توسط این افزونه تأیید کند، مرورگر از افزونه درخواست می‌کند تا داده‌ها را برای ادامه‌ی TLS handshake امضا کند. این درخواست به عنوان یک رویداد onSignatureRequested ارسال می‌شود.
  • این رویداد شامل داده‌های ورودی است، الگوریتمی را که باید برای تولید امضا استفاده شود، اعلام می‌کند و به یکی از گواهی‌هایی که توسط این افزونه گزارش شده است، اشاره دارد. افزونه باید با استفاده از کلید خصوصی مرتبط با گواهی ارجاع شده، امضایی برای داده‌های داده شده ایجاد کند. ایجاد امضا ممکن است نیاز به افزودن یک DigestInfo به ابتدای آن و پر کردن نتیجه قبل از امضای واقعی داشته باشد.
  • افزونه با استفاده از متد reportSignature امضا را به مرورگر ارسال می‌کند. اگر امضا قابل محاسبه نباشد، باید متد بدون امضا فراخوانی شود.
  • اگر امضا ارائه شده باشد، مرورگر فرآیند TLS handshake را تکمیل می‌کند.

توالی واقعی مراحل می‌تواند متفاوت باشد. برای مثال، اگر از سیاست سازمانی برای انتخاب خودکار گواهی استفاده شود، از کاربر خواسته نمی‌شود که گواهی را انتخاب کند (به 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

کروم ۸۶+

انواع الگوریتم‌های امضای رمزنگاری پشتیبانی‌شده

شمارشی

«RSASSA_PKCS1_v1_5_MD5_SHA1»
الگوریتم امضای RSASSA PKCS#1 v1.5 را با هشینگ MD5-SHA-1 مشخص می‌کند. افزونه نباید پیشوند DigestInfo را اضافه کند، بلکه فقط باید فاصله‌گذاری PKCS#1 را اضافه کند. این الگوریتم منسوخ شده است و از نسخه ۱۰۹ به بعد دیگر توسط کروم درخواست نخواهد شد.

«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

خواص

  • گواهی

    آرایه بافر

    باید کدگذاری DER گواهی X.509 باشد. در حال حاضر، فقط گواهی‌های کلیدهای RSA پشتیبانی می‌شوند.

  • هش‌های پشتیبانی‌شده

    هش []

    باید روی تمام هش‌های پشتیبانی‌شده برای این گواهی تنظیم شود. این افزونه فقط برای امضاهای خلاصه‌های محاسبه‌شده با یکی از این الگوریتم‌های هش درخواست می‌شود. این باید به ترتیب کاهش اولویت هش باشد.

CertificatesUpdateRequest

کروم ۸۶+

خواص

  • شناسه درخواست گواهینامه‌ها

    شماره

    درخواست ارسال شناسه به setCertificates .

ClientCertificateInfo

کروم ۸۶+

خواص

  • گواهینامه زنجیره‌ای

    آرایه بافر[]

    این آرایه باید به عنوان اولین عنصر خود، شامل کدگذاری DER مربوط به گواهی کلاینت X.509 باشد.

    این باید دقیقاً شامل یک گواهی باشد.

  • الگوریتم‌های پشتیبانی‌شده

    الگوریتم []

    تمام الگوریتم‌های پشتیبانی‌شده برای این گواهی. افزونه فقط با استفاده از یکی از این الگوریتم‌ها امضا درخواست خواهد کرد.

Error

کروم ۸۶+

انواع خطاهایی که افزونه می‌تواند گزارش دهد.

ارزش

"خطای عمومی"

Hash

منسوخ شده. با Algorithm جایگزین شده است.

شمارشی

"MD5_SHA1"
الگوریتم‌های هشینگ MD5 و SHA1 را مشخص می‌کند.

«شا۱»
الگوریتم هشینگ SHA1 را مشخص می‌کند.

«شا۲۵۶»
الگوریتم هشینگ SHA256 را مشخص می‌کند.

«شا۳۸۴»
الگوریتم هشینگ SHA384 را مشخص می‌کند.

«شا۵۱۲»
الگوریتم هشینگ SHA512 را مشخص می‌کند.

PinRequestErrorType

کروم ۵۷+

انواع خطاهایی که می‌توانند از طریق تابع requestPin به کاربر ارائه شوند.

شمارشی

"پین_نامعتبر"
مشخص می‌کند که پین ​​نامعتبر است.

"نامعتبر_PUK"
مشخص می‌کند که PUK نامعتبر است.

"حداکثر دما از حد مجاز گذشت"
مشخص می‌کند که از حداکثر تعداد تلاش تجاوز شده است.

«خطای_ناشناخته»
مشخص می‌کند که خطا نمی‌تواند توسط انواع فوق نمایش داده شود.

PinRequestType

کروم ۵۷+

نوع کدی که توسط افزونه با تابع requestPin درخواست می‌شود.

شمارشی

"پین"
مشخص می‌کند که کد درخواستی یک پین است.

"پی یو کی"
مشخص می‌کند که کد درخواستی یک PUK است.

PinResponseDetails

کروم ۵۷+

خواص

  • ورودی کاربر

    رشته اختیاری

    کدی که توسط کاربر ارائه شده است. در صورتی که کاربر کادر محاوره‌ای را ببندد یا خطای دیگری رخ دهد، خالی می‌ماند.

ReportSignatureDetails

کروم ۸۶+

خواص

  • خطا

    "خطای عمومی"
    اختیاری

    خطایی که هنگام تولید امضا رخ داده است، در صورت وجود.

  • شناسه درخواست امضا

    شماره

    شناسه درخواستی که از طریق رویداد onSignatureRequested دریافت شده است.

  • امضا

    ArrayBuffer اختیاری

    امضا، در صورت موفقیت‌آمیز بودن تولید.

RequestPinDetails

کروم ۵۷+

خواص

  • تلاش‌هاچپ

    شماره اختیاری

    تعداد تلاش‌های باقی‌مانده. این اطلاعات به گونه‌ای ارائه می‌شود که هر رابط کاربری بتواند این اطلاعات را به کاربر ارائه دهد. انتظار نمی‌رود کروم این را اجباری کند، در عوض، وقتی تعداد درخواست‌های پین از حد مجاز فراتر می‌رود، باید stopPinRequest توسط افزونه با errorType = MAX_ATTEMPTS_EXCEEDED فراخوانی شود.

  • نوع خطا

    نوع خطای درخواست پین اختیاری است

    الگوی خطایی که به کاربر نمایش داده می‌شود. این الگو باید در صورت عدم موفقیت درخواست قبلی تنظیم شود تا دلیل عدم موفقیت به کاربر اطلاع داده شود.

  • نوع درخواست

    نوع درخواست پین اختیاری

    نوع کد درخواستی. پیش‌فرض پین است.

  • شناسه درخواست امضا

    شماره

    شناسه‌ای که کروم در SignRequest ارائه می‌دهد.

SetCertificatesDetails

کروم ۸۶+

خواص

  • شناسه درخواست گواهینامه‌ها

    شماره اختیاری

    وقتی در پاسخ به onCertificatesUpdateRequested فراخوانی می‌شود، باید حاوی مقدار certificatesRequestId دریافتی باشد. در غیر این صورت، باید مقدار آن تنظیم نشده باشد.

  • گواهینامه‌های مشتری

    اطلاعات گواهینامه مشتری []

    فهرست گواهی‌های مشتری موجود در حال حاضر.

  • خطا

    "خطای عمومی"
    اختیاری

    خطایی که هنگام استخراج گواهی‌ها رخ داده است، در صورت وجود. این خطا در زمان مناسب به کاربر اطلاع داده خواهد شد.

SignatureRequest

کروم ۸۶+

خواص

  • الگوریتم

    الگوریتم

    الگوریتم امضا مورد استفاده.

  • گواهی

    آرایه بافر

    کدگذاری DER گواهی X.509. افزونه باید input با استفاده از کلید خصوصی مرتبط امضا کند.

  • ورودی

    آرایه بافر

    داده‌هایی که باید امضا شوند. توجه داشته باشید که داده‌ها هش نشده‌اند.

  • شناسه درخواست امضا

    شماره

    درخواست ارسال شناسه به reportSignature .

SignRequest

خواص

  • گواهی

    آرایه بافر

    کدگذاری DER گواهی X.509. افزونه باید با استفاده از کلید خصوصی مرتبط، digest را امضا کند.

  • هضم

    آرایه بافر

    خلاصه‌ای که باید امضا شود.

  • هش

    هش

    به الگوریتم هش مورد استفاده برای ایجاد digest اشاره دارد.

  • شناسه درخواست امضا

    شماره

    کروم ۵۷+

    شناسه‌ی منحصر به فردی که افزونه در صورت نیاز به فراخوانی متدی که به آن نیاز دارد، مانند requestPin، از آن استفاده خواهد کرد.

StopPinRequestDetails

کروم ۵۷+

خواص

  • نوع خطا

    نوع خطای درخواست پین اختیاری است

    الگوی خطا. در صورت وجود، به کاربر نمایش داده می‌شود. هدف آن درج دلیل توقف جریان در صورتی است که ناشی از خطا باشد، مثلاً MAX_ATTEMPTS_EXCEEDED.

  • شناسه درخواست امضا

    شماره

    شناسه‌ای که کروم در SignRequest ارائه می‌دهد.

روش‌ها

reportSignature()

قول کروم ۸۶+
chrome.certificateProvider.reportSignature(
  details: ReportSignatureDetails,
  callback?: function,
): Promise<void>

باید به عنوان پاسخی به onSignatureRequested فراخوانی شود.

این افزونه در نهایت باید این تابع را برای هر رویداد onSignatureRequested فراخوانی کند؛ پیاده‌سازی API پس از مدتی انتظار برای این فراخوانی را متوقف می‌کند و هنگام فراخوانی این تابع، با یک خطای timeout پاسخ می‌دهد.

پارامترها

بازگشت‌ها

  • قول<void>

    کروم ۹۶+

    Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.

requestPin()

قول کروم ۵۷+
chrome.certificateProvider.requestPin(
  details: RequestPinDetails,
  callback?: function,
): Promise<PinResponseDetails | undefined>

پین را از کاربر درخواست می‌کند. فقط یک درخواست در حال انجام در هر زمان مجاز است. درخواست‌هایی که در حین جریان دیگری صادر می‌شوند، رد می‌شوند. اگر جریان دیگری در حال انجام باشد، این مسئولیت افزونه است که بعداً دوباره امتحان کند.

پارامترها

بازگشت‌ها

  • قول< جزئیات پاسخ پین | تعریف نشده>

    کروم ۹۶+

    یک Promise برمی‌گرداند که با ارائه PIN توسط کاربر، اجرا می‌شود. اگر درخواست دیالوگ با موفقیت به پایان نرسد (مثلاً دیالوگ توسط کاربر لغو شده یا اجازه نمایش نداشته باشد)، با خطا رد می‌شود.

    Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.

setCertificates()

قول کروم ۸۶+
chrome.certificateProvider.setCertificates(
  details: SetCertificatesDetails,
  callback?: function,
): Promise<void>

فهرستی از گواهی‌ها را برای استفاده در مرورگر تنظیم می‌کند.

افزونه باید این تابع را پس از مقداردهی اولیه و با هر تغییر در مجموعه گواهی‌های موجود فعلی فراخوانی کند. افزونه همچنین باید این تابع را در پاسخ به onCertificatesUpdateRequested هر بار که این رویداد دریافت می‌شود، فراخوانی کند.

پارامترها

  • گواهی‌هایی که باید تنظیم شوند. گواهی‌های نامعتبر نادیده گرفته می‌شوند.

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به شکل زیر است: 

    () => void

بازگشت‌ها

  • قول<void>

    کروم ۹۶+

    یک Promise برمی‌گرداند که پس از اتمام، برطرف می‌شود.

    Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.

stopPinRequest()

قول کروم ۵۷+
chrome.certificateProvider.stopPinRequest(
  details: StopPinRequestDetails,
  callback?: function,
): Promise<void>

درخواست پین آغاز شده توسط تابع requestPin را متوقف می‌کند.

پارامترها

بازگشت‌ها

  • قول<void>

    کروم ۹۶+

    یک Promise برمی‌گرداند که پس از اتمام درخواست بستن کادر محاوره‌ای PIN، اجرا می‌شود.

    Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.

رویدادها

onCertificatesRequested

کروم ۴۷+ ≤ MV2 از کروم ۸۶ منسوخ شده است
 
chrome.certificateProvider.onCertificatesRequested.addListener(
  callback: function,
)

به جای آن onCertificatesUpdateRequested استفاده کنید.

این رویداد هر بار که مرورگر لیست فعلی گواهی‌های ارائه شده توسط این افزونه را درخواست می‌کند، فعال می‌شود. افزونه باید دقیقاً یک بار reportCallback را با لیست فعلی گواهی‌ها فراخوانی کند.

پارامترها

  • تماس برگشتی

    تابع

    پارامتر callback به شکل زیر است: 

    (reportCallback: function) => void

    • گزارشتماس برگشتی

      تابع

      پارامتر reportCallback به شکل زیر است: 

      (certificates: CertificateInfo[], callback: function) => void

      • گواهینامه ها

        اطلاعات گواهینامه []

      • تماس برگشتی

        تابع

        پارامتر callback به شکل زیر است: 

        (rejectedCertificates: ArrayBuffer[]) => void

        • گواهینامه‌های رد شده

          آرایه بافر[]

onCertificatesUpdateRequested

کروم ۸۶+
chrome.certificateProvider.onCertificatesUpdateRequested.addListener(
  callback: function,
)

This event fires if the certificates set via setCertificates are insufficient or the browser requests updated information. The extension must call setCertificates with the updated list of certificates and the received certificatesRequestId .

پارامترها

onSignatureRequested

کروم ۸۶+
chrome.certificateProvider.onSignatureRequested.addListener(
  callback: function,
)

این رویداد هر بار که مرورگر نیاز به امضای پیامی با استفاده از گواهی ارائه شده توسط این افزونه از طریق setCertificates داشته باشد، فعال می‌شود.

افزونه باید داده‌های ورودی از request را با استفاده از الگوریتم و کلید خصوصی مناسب امضا کند و آن را با فراخوانی reportSignature با signRequestId دریافتی بازگرداند.

پارامترها

onSignDigestRequested

≤ MV2 از زمان کروم ۸۶ منسوخ شده است
 
chrome.certificateProvider.onSignDigestRequested.addListener(
  callback: function,
)

به جای آن onSignatureRequested استفاده کنید.

این رویداد هر بار که مرورگر نیاز به امضای پیامی با استفاده از گواهی ارائه شده توسط این افزونه در پاسخ به رویداد onCertificatesRequested داشته باشد، فعال می‌شود. افزونه باید داده‌های request را با استفاده از الگوریتم و کلید خصوصی مناسب امضا کند و آن را با فراخوانی reportCallback بازگرداند. reportCallback باید دقیقاً یک بار فراخوانی شود.

پارامترها

  • تماس برگشتی

    تابع

    پارامتر callback به شکل زیر است: 

    (request: SignRequest, reportCallback: function) => void

    • درخواست

      درخواست امضا

    • گزارشتماس برگشتی

      تابع

      کروم ۴۷+

      پارامتر reportCallback به شکل زیر است: 

      (signature?: ArrayBuffer) => void

      • امضا

        ArrayBuffer اختیاری