chrome.certificateProvider

توضیحات

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

مجوزها

certificateProvider

در دسترس بودن

فقط Chrome 46+ ChromeOS

مفاهیم و کاربرد

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

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

توالی واقعی مراحل می تواند متفاوت باشد. برای مثال، اگر از خط‌مشی سازمانی برای انتخاب خودکار گواهی استفاده شود، از کاربر خواسته نمی‌شود که گواهی را انتخاب کند (به AutoSelectCertificateForUrls و خط‌مشی‌های Chrome برای کاربران مراجعه کنید).

در Extension، این می تواند شبیه قطعه زیر باشد:

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 درخواست نخواهد شد.

"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 پشتیبانی می‌شوند.

  • هش ها را پشتیبانی کرد

    هش []

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

CertificatesUpdateRequest

Chrome 86+

خواص

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

    شماره

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

ClientCertificateInfo

Chrome 86+

خواص

  • CertificCchain

    ArrayBuffer[]

    آرایه باید حاوی رمزگذاری DER گواهی مشتری X.509 به عنوان اولین عنصر باشد.

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

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

    الگوریتم []

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

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

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

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

PinResponseDetails

Chrome 57+

خواص

  • userInput

    رشته اختیاری

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

ReportSignatureDetails

Chrome 86+

خواص

  • خطا

    "GENERAL_ERROR"
    اختیاری

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

  • signRequestId

    شماره

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

  • امضا

    ArrayBuffer اختیاری است

    امضا، اگر با موفقیت ایجاد شود.

RequestPinDetails

Chrome 57+

خواص

  • تلاش چپ

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

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

  • نوع خطا

    PinRequestErrorType اختیاری است

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

  • نوع درخواست

    PinRequestType اختیاری است

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

  • signRequestId

    شماره

    شناسه ارائه شده توسط Chrome در SignRequest.

SetCertificatesDetails

Chrome 86+

خواص

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

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

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

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

    ClientCertificateInfo []

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

  • خطا

    "GENERAL_ERROR"
    اختیاری

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

SignatureRequest

Chrome 86+

خواص

  • الگوریتم

    الگوریتم

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

  • گواهی

    ArrayBuffer

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

  • ورودی

    ArrayBuffer

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

  • signRequestId

    شماره

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

SignRequest

خواص

  • گواهی

    ArrayBuffer

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

  • هضم

    ArrayBuffer

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

  • هش

    هش

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

  • signRequestId

    شماره

    Chrome 57+

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

StopPinRequestDetails

Chrome 57+

خواص

  • نوع خطا

    PinRequestErrorType اختیاری است

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

  • signRequestId

    شماره

    شناسه ارائه شده توسط Chrome در SignRequest.

روش ها

reportSignature()

Promise Chrome 86+
chrome.certificateProvider.reportSignature(
  details: ReportSignatureDetails,
  callback?: function,
)

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

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

پارامترها

  • جزئیات

    ReportSignatureDetails

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    () => void

برمی گرداند

  • قول<باطل>

    Chrome 96+

    Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

requestPin()

Promise Chrome 57+
chrome.certificateProvider.requestPin(
  details: RequestPinDetails,
  callback?: function,
)

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

پارامترها

  • جزئیات

    RequestPinDetails

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

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    (details?: PinResponseDetails) => void

برمی گرداند

  • Promise< PinResponseDetails | تعریف نشده>

    Chrome 96+

    Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

setCertificates()

Promise Chrome 86+
chrome.certificateProvider.setCertificates(
  details: SetCertificatesDetails,
  callback?: function,
)

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

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

پارامترها

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

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    () => void

برمی گرداند

  • قول<باطل>

    Chrome 96+

    Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

stopPinRequest()

Promise Chrome 57+
chrome.certificateProvider.stopPinRequest(
  details: StopPinRequestDetails,
  callback?: function,
)

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

پارامترها

  • جزئیات

    StopPinRequestDetails

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

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    () => void

برمی گرداند

  • قول<باطل>

    Chrome 96+

    Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

رویدادها

onCertificatesRequested

Chrome 47+ ≤ MV2 از Chrome 86 منسوخ شده است
 
chrome.certificateProvider.onCertificatesRequested.addListener(
  callback: function,
)

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

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

پارامترها

  • پاسخ به تماس

    تابع

    پارامتر callback به نظر می رسد: 

    (reportCallback: function) => void

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

      تابع

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

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

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

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

      • پاسخ به تماس

        تابع

        پارامتر callback به نظر می رسد: 

        (rejectedCertificates: ArrayBuffer[]) => void

        • گواهی های رد شده

          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

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

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

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

پارامترها

  • پاسخ به تماس

    تابع

    پارامتر callback به نظر می رسد: 

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

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

      SignRequest

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

      تابع

      Chrome 47+

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

      (signature?: ArrayBuffer) => void

      • امضا

        ArrayBuffer اختیاری است