chrome.certificateProvider

refresh date: 2026-09-25 robots: noindex

شرح

از این میانای برنامه‌سازی کاربردی برای نمایش گواهینامه‌ها به پلاتفرمی استفاده کنید که می‌تواند از این گواهینامه‌ها برای اصالت‌سنجی‌های «امنیت لایه انتقال» استفاده کند.

اجازه‌ها

certificateProvider

دردسترس بودن

Chrome نسخه ۴۶ به بالا فقط ChromeOS

کاربرد

استفاده معمول از این میانای برنامه‌سازی کاربردی برای نمایش گواهینامه‌های کارخواه در 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 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 نسخه ۸۶ و بالاتر

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

شمارشی

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

"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

    درهم‌سازی[]

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

CertificatesUpdateRequest

Chrome نسخه ۸۶ و بالاتر

مشخصات

  • certificatesRequestId

    شماره

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

ClientCertificateInfo

Chrome نسخه ۸۶ و بالاتر

مشخصات

  • certificateChain

    ArrayBuffer[]

    آرایه باید حاوی کدگذاری DER گواهی کارخواه X.509 به‌عنوان اولین عنصر آن باشد.

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

  • supportedAlgorithms

    الگوریتم[]

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

Error

Chrome نسخه ۸۶ و بالاتر

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

مقدار

"GENERAL_ERROR"

Hash

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

شمارشی

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

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

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

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

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

PinRequestErrorType

Chrome نسخه ۵۷ و بالاتر

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

شمارشی

«INVALID_PIN»
مشخص می‌کند پین نامعتبر است.

«INVALID_PUK»
مشخص می‌کند که PUK نامعتبر است.

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

«UNKNOWN_ERROR»
مشخص می‌کند که خطا را نمی‌توان با انواع بالا نشان داد.

PinRequestType

Chrome نسخه ۵۷ و بالاتر

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

شمارشی

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

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

PinResponseDetails

Chrome نسخه ۵۷ و بالاتر

مشخصات

  • userInput

    رشته اختیاری

    کد ارائه‌شده توسط کاربر. اگر کاربر کادر گفتگو را بسته باشد یا خطای دیگری رخ داده باشد، خالی است.

ReportSignatureDetails

Chrome نسخه ۸۶ و بالاتر

مشخصات

  • خطا

    "GENERAL_ERROR"
     اختیاری

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

  • signRequestId

    شماره

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

  • امضا

    ArrayBuffer اختیاری

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

RequestPinDetails

Chrome نسخه ۵۷ و بالاتر

مشخصات

  • attemptsLeft

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

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

  • errorType

    PinRequestErrorType اختیاری

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

  • requestType

    PinRequestType اختیاری

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

  • signRequestId

    شماره

    شناسه‌ای که Chrome در SignRequest ارائه کرده است.

SetCertificatesDetails

Chrome نسخه ۸۶ و بالاتر

مشخصات

  • certificatesRequestId

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

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

  • clientCertificates

    ClientCertificateInfo[]

    فهرست گواهینامه‌های کارخواه که درحال‌حاضر دردسترس است.

  • خطا

    "GENERAL_ERROR"
     اختیاری

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

SignatureRequest

Chrome نسخه ۸۶ و بالاتر

مشخصات

  • الگوریتم

    الگوریتم

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

  • گواهی‌نامه

    ArrayBuffer

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

  • ورودی

    ArrayBuffer

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

  • signRequestId

    شماره

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

SignRequest

مشخصات

  • گواهی‌نامه

    ArrayBuffer

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

  • خلاصه

    ArrayBuffer

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

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

  • signRequestId

    شماره

    Chrome نسخه ۵۷ و بالاتر

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

StopPinRequestDetails

Chrome نسخه ۵۷ و بالاتر

مشخصات

  • errorType

    PinRequestErrorType اختیاری

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

  • signRequestId

    شماره

    شناسه‌ای که Chrome در SignRequest ارائه کرده است.

روش‌ها

reportSignature()

Promise Chrome نسخه ۸۶ و بالاتر 
chrome.certificateProvider.reportSignature(
  details: ReportSignatureDetails,
  callback?: function,
): Promise<void>

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

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

پارامترها

  • جزئیات

    ReportSignatureDetails

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    () => void

بازگشتی‌ها

  • Promise<void>

    Chrome نسخه ۹۶ به بالا

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

requestPin()

Promise Chrome نسخه ۵۷ و بالاتر 
chrome.certificateProvider.requestPin(
  details: RequestPinDetails,
  callback?: function,
): Promise<PinResponseDetails | undefined>

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

پارامترها

  • جزئیات

    RequestPinDetails

    حاوی جزئیات مربوط به کادر گفتگوی درخواست‌شده است.

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    (details?: PinResponseDetails) => void

بازگشتی‌ها

  • Promise<PinResponseDetails | undefined>

    Chrome نسخه ۹۶ به بالا

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

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

setCertificates()

Promise Chrome نسخه ۸۶ و بالاتر 
chrome.certificateProvider.setCertificates(
  details: SetCertificatesDetails,
  callback?: function,
): Promise<void>

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

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

پارامترها

  • جزئیات

    SetCertificatesDetails

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

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    () => void

بازگشتی‌ها

  • Promise<void>

    Chrome نسخه ۹۶ به بالا

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

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

stopPinRequest()

Promise Chrome نسخه ۵۷ و بالاتر 
chrome.certificateProvider.stopPinRequest(
  details: StopPinRequestDetails,
  callback?: function,
): Promise<void>

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

پارامترها

  • جزئیات

    StopPinRequestDetails

    حاوی جزئیات مربوط به دلیل توقف جریان درخواست است.

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    () => void

بازگشتی‌ها

  • Promise<void>

    Chrome نسخه ۹۶ به بالا

    یک Promise برمی‌گرداند که وقتی درخواست بستن کادر گفتگوی پین تکمیل شود، حل می‌شود.

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

رویدادها

onCertificatesRequested

Chrome نسخه ۴۷ و بالاتر &leq; MV2 از Chrome نسخه ۸۶ منسوخ شده است
chrome.certificateProvider.onCertificatesRequested.addListener(
  callback: function,
)

درعوض از onCertificatesUpdateRequested استفاده کنید.

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

پارامترها

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

    (reportCallback: function) => void

    • reportCallback

      عملکرد

      پارامتر reportCallback به‌صورت زیر است: 

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

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

        CertificateInfo[]

      • تماس برگشتی

        عملکرد

        پارامتر callback به‌صورت زیر است: 

        (rejectedCertificates: ArrayBuffer[]) => void

        • rejectedCertificates

          ArrayBuffer[]

onCertificatesUpdateRequested

Chrome نسخه ۸۶ و بالاتر 
chrome.certificateProvider.onCertificatesUpdateRequested.addListener(
  callback: function,
)

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

پارامترها

onSignatureRequested

Chrome نسخه ۸۶ و بالاتر 
chrome.certificateProvider.onSignatureRequested.addListener(
  callback: function,
)

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

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

پارامترها

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

    (request: SignatureRequest) => void

onSignDigestRequested

&leq; MV2 از Chrome 86 منسوخ شده است
chrome.certificateProvider.onSignDigestRequested.addListener(
  callback: function,
)

درعوض از onSignatureRequested استفاده کنید.

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

پارامترها

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

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

    • درخواست کردن

      SignRequest

    • reportCallback

      عملکرد

      Chrome نسخه ۴۷ و بالاتر

      پارامتر reportCallback به‌صورت زیر است: 

      (signature?: ArrayBuffer) => void

      • امضا

        ArrayBuffer اختیاری