chrome.certificateProvider

Deskripsi

Gunakan API ini untuk mengekspos sertifikat ke platform yang dapat menggunakan sertifikat tersebut untuk autentikasi TLS.

Izin

certificateProvider

Ketersediaan

Chrome 46+ Khusus ChromeOS

Konsep dan penggunaan

Penggunaan standar API ini untuk mengekspos sertifikat klien ke ChromeOS mengikuti langkah-langkah berikut:

  • Ekstensi mendaftar untuk peristiwa onCertificatesUpdateRequested dan onSignatureRequested.
  • Ekstensi memanggil setCertificates() untuk memberikan daftar awal sertifikat setelah inisialisasi.
  • Ekstensi memantau perubahan dalam daftar sertifikat yang tersedia dan memanggil setCertificates() untuk memberi tahu browser tentang setiap perubahan tersebut.
  • Selama TLS handshake, browser menerima permintaan sertifikat klien. Dengan peristiwa onCertificatesUpdateRequested, browser akan meminta Ekstensi untuk melaporkan semua sertifikat yang saat ini disediakan.
  • Ekstensi melaporkan kembali dengan sertifikat yang saat ini tersedia, menggunakan metode setCertificates().
  • Browser mencocokkan semua sertifikat yang tersedia dengan permintaan sertifikat klien dari host jarak jauh. Hasil yang cocok akan ditampilkan kepada pengguna dalam dialog pemilihan.
  • Pengguna dapat memilih sertifikat dan dengan demikian menyetujui otentikasi atau membatalkan otentikasi.
Dialog pemilihan sertifikat
Dialog pemilihan sertifikat.
  • Jika pengguna membatalkan autentikasi atau tidak ada sertifikat yang cocok dengan permintaan, autentikasi klien TLS akan dibatalkan.
  • Atau, jika pengguna menyetujui autentikasi dengan sertifikat yang disediakan oleh Ekstensi ini, browser akan meminta Ekstensi untuk menandatangani data guna melanjutkan TLS handshake. Permintaan dikirim sebagai peristiwa onSignatureRequested.
  • Peristiwa ini berisi data input, mendeklarasikan algoritma mana yang harus digunakan untuk membuat tanda tangan, dan merujuk pada salah satu sertifikat yang dilaporkan oleh Ekstensi ini. Ekstensi harus membuat tanda tangan untuk data tertentu menggunakan kunci pribadi yang terkait dengan sertifikat yang direferensikan. Membuat tanda tangan mungkin memerlukan awalan DigestInfo dan padding pada hasilnya sebelum penandatanganan yang sebenarnya.
  • Ekstensi mengirimkan kembali tanda tangan ke browser menggunakan metode reportSignature(). Jika tanda tangan tidak dapat dihitung, metode harus dipanggil tanpa tanda tangan.
  • Jika tanda tangan diberikan, browser akan melengkapi handshake TLS.

Urutan langkah yang sebenarnya dapat berbeda. Misalnya, pengguna tidak akan diminta memilih sertifikat jika digunakan kebijakan perusahaan untuk memilih sertifikat secara otomatis (lihat AutoSelectCertificateForUrls dan kebijakan Chrome untuk pengguna).

Di Ekstensi, cuplikannya dapat terlihat seperti berikut:

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);

Jenis

Algorithm

Chrome 86 dan yang lebih baru

Jenis algoritma tanda tangan kriptografi yang didukung.

Enum

"RSASSA_PKCS1_v1_5_MD5_SHA1"
Menentukan algoritma tanda tangan RSASSA PKCS#1 v1.5 dengan hashing MD5-SHA-1. Ekstensi tidak boleh menambahkan awalan DigestInfo, tetapi hanya menambahkan padding PKCS#1. Algoritma ini tidak digunakan lagi dan tidak akan pernah diminta oleh Chrome mulai versi 109.

"RSASSA_PKCS1_v1_5_SHA1"
Menentukan algoritma tanda tangan RSASSA PKCS#1 v1.5 dengan fungsi hash SHA-1.

"RSASSA_PKCS1_v1_5_SHA256"
Menentukan algoritma tanda tangan RSASSA PKCS#1 v1.5 dengan fungsi hashing SHA-256.

"RSASSA_PKCS1_v1_5_SHA384"
Menentukan algoritma tanda tangan RSASSA PKCS#1 v1.5 dengan fungsi hashing SHA-384.

"RSASSA_PKCS1_v1_5_SHA512"
Menentukan algoritma tanda tangan RSASSA PKCS#1 v1.5 dengan fungsi hashing SHA-512.

"RSASSA_PSS_SHA256"
Menentukan algoritma tanda tangan RSASSA PSS dengan fungsi hashing SHA-256, fungsi pembuatan mask MGF1, dan salt yang berukuran sama dengan hash.

"RSASSA_PSS_SHA384"
Menentukan algoritma tanda tangan RSASSA PSS dengan fungsi hashing SHA-384, fungsi pembuatan mask MGF1, dan salt yang berukuran sama dengan hash.

"RSASSA_PSS_SHA512"
Menentukan algoritma tanda tangan RSASSA PSS dengan fungsi hashing SHA-512, fungsi pembuatan mask MGF1, dan salt yang berukuran sama dengan hash.

CertificateInfo

Properti

  • sertifikat

    ArrayBuffer

    Harus berupa encoding DER untuk sertifikat X.509. Saat ini, hanya sertifikat kunci RSA yang didukung.

  • supportedHashes

    Hash[]

    Harus ditetapkan ke semua hash yang didukung untuk sertifikat ini. Ekstensi ini hanya akan diminta untuk tanda tangan ringkasan yang dihitung dengan salah satu algoritma hash ini. Ini harus dilakukan untuk mengurangi preferensi hash.

CertificatesUpdateRequest

Chrome 86 dan yang lebih baru

Properti

  • certificatesRequestId

    angka

    Minta ID untuk diteruskan ke setCertificates.

ClientCertificateInfo

Chrome 86 dan yang lebih baru

Properti

  • certificateChain

    ArrayBuffer[]

    Array harus berisi encoding DER sertifikat klien X.509 sebagai elemen pertamanya.

    Sertifikat ini harus menyertakan tepat satu sertifikat.

  • supportedAlgorithms

    Algoritma[]

    Semua algoritma yang didukung untuk sertifikat ini. Ekstensi hanya akan dimintai tanda tangan menggunakan salah satu algoritma ini.

Error

Chrome 86 dan yang lebih baru

Jenis error yang dapat dilaporkan oleh ekstensi.

Nilai

"GENERAL_ERROR"

Hash

Tidak digunakan lagi. Diganti dengan Algorithm.

Enum

"MD5_SHA1"
Menentukan algoritma hashing MD5 dan SHA1.

"SHA1"
Menentukan algoritma hashing SHA1.

"SHA256"
Menentukan algoritma hashing SHA256.

"SHA384"
Menentukan algoritma hashing SHA384.

"SHA512"
Menentukan algoritma hashing SHA512.

PinRequestErrorType

Chrome 57 dan yang lebih baru

Jenis error yang dapat ditampilkan kepada pengguna melalui fungsi requestPin.

Enum

"INVALID_PIN"
Menentukan PIN tidak valid.

"INVALID_PUK"
Menentukan PUK tidak valid.

"MAX_ATTEMPTS_EXCEEDED"
Menentukan jumlah upaya maksimum telah terlampaui.

"UNKNOWN_ERROR"
Menentukan bahwa error tidak dapat ditunjukkan oleh jenis di atas.

PinRequestType

Chrome 57 dan yang lebih baru

Jenis kode yang diminta oleh ekstensi dengan fungsi requestPin.

Enum

"PIN"
Menentukan kode yang diminta adalah PIN.

"PUK"
Menentukan kode yang diminta adalah PUK.

PinResponseDetails

Chrome 57 dan yang lebih baru

Properti

  • userInput

    string opsional

    Kode yang diberikan oleh pengguna. Kosong jika pengguna menutup dialog atau terjadi error lainnya.

ReportSignatureDetails

Chrome 86 dan yang lebih baru

Properti

  • error

     opsional

    Error yang terjadi saat membuat tanda tangan, jika ada.

  • signRequestId

    angka

    Minta ID yang diterima melalui peristiwa onSignatureRequested.

  • tanda tangan

    ArrayBuffer opsional

    Tanda tangan, jika berhasil dibuat.

RequestPinDetails

Chrome 57 dan yang lebih baru

Properti

  • attemptsLeft

    nomor opsional

    Jumlah upaya yang tersisa. Info ini disediakan sehingga UI apa pun dapat menyajikan informasi ini kepada pengguna. Chrome tidak diharapkan untuk menerapkan hal ini, sebagai gantinya stopPinRequest harus dipanggil oleh ekstensi dengan errorType = MAX_attemptS_EXCEEDED saat jumlah permintaan pin terlampaui.

  • errorType

    PinRequestErrorType opsional

    Template error yang ditampilkan kepada pengguna. Atribut ini harus ditetapkan jika permintaan sebelumnya gagal, untuk memberi tahu pengguna tentang alasan kegagalan.

  • requestType

    PinRequestType opsional

    Jenis kode yang diminta. Default-nya adalah PIN.

  • signRequestId

    angka

    ID yang diberikan oleh Chrome di SignRequest.

SetCertificatesDetails

Chrome 86 dan yang lebih baru

Properti

  • certificatesRequestId

    nomor opsional

    Saat dipanggil sebagai respons terhadap onCertificatesUpdateRequested, harus berisi nilai certificatesRequestId yang diterima. Jika tidak, harus dibatalkan penetapannya.

  • clientCertificates

    ClientCertificateInfo[]

    Daftar sertifikat klien yang saat ini tersedia.

  • error

     opsional

    Error yang terjadi saat mengekstrak sertifikat, jika ada. Error ini akan ditampilkan kepada pengguna jika sesuai.

SignatureRequest

Chrome 86 dan yang lebih baru

Properti

  • algoritme

    Algoritma

    Algoritma tanda tangan yang akan digunakan.

  • sertifikat

    ArrayBuffer

    Encoding DER sertifikat X.509. Ekstensi harus menandatangani input menggunakan kunci pribadi yang terkait.

  • input

    ArrayBuffer

    Data yang akan ditandatangani. Perhatikan bahwa data tidak di-hash.

  • signRequestId

    angka

    Minta ID untuk diteruskan ke reportSignature.

SignRequest

Properti

  • sertifikat

    ArrayBuffer

    Encoding DER sertifikat X.509. Ekstensi harus menandatangani digest menggunakan kunci pribadi yang terkait.

  • digest

    ArrayBuffer

    Ringkasan yang harus ditandatangani.

  • hash

    Hash

    Merujuk pada algoritma hash yang digunakan untuk membuat digest.

  • signRequestId

    angka

    Chrome 57 dan yang lebih baru

    ID unik yang akan digunakan oleh ekstensi jika ekstensi perlu memanggil metode yang memerlukannya, mis. requestPin.

StopPinRequestDetails

Chrome 57 dan yang lebih baru

Properti

  • errorType

    PinRequestErrorType opsional

    Template error. Jika ada, data akan ditampilkan kepada pengguna. Dimaksudkan untuk mencantumkan alasan penghentian alur jika disebabkan oleh error, misalnya, MAX_attemptS_EXCEEDED.

  • signRequestId

    angka

    ID yang diberikan oleh Chrome di SignRequest.

Metode

reportSignature()

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

Harus dipanggil sebagai respons terhadap onSignatureRequested.

Ekstensi nantinya harus memanggil fungsi ini untuk setiap peristiwa onSignatureRequested; implementasi API akan berhenti menunggu panggilan ini setelah beberapa waktu dan merespons dengan error waktu tunggu saat fungsi ini dipanggil.

Parameter

Hasil

  • Promise<void>

    Chrome 96 dan yang lebih baru

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.

requestPin()

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

Meminta PIN dari pengguna. Hanya satu permintaan berkelanjutan dalam satu waktu yang diizinkan. Permintaan yang dikeluarkan saat alur lain sedang berlangsung akan ditolak. Ekstensi bertanggung jawab untuk mencoba lagi nanti jika alur lain sedang berlangsung.

Parameter

Hasil

  • Promise<PinResponseDetails|undefined>

    Chrome 96 dan yang lebih baru

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.

setCertificates()

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

Menetapkan daftar sertifikat untuk digunakan di browser.

Ekstensi harus memanggil fungsi ini setelah inisialisasi dan pada setiap perubahan dalam kumpulan sertifikat yang saat ini tersedia. Ekstensi juga harus memanggil fungsi ini sebagai respons terhadap onCertificatesUpdateRequested setiap kali peristiwa ini diterima.

Parameter

  • Sertifikat yang akan ditetapkan. Sertifikat yang tidak valid akan diabaikan.

  • callback

    fungsi opsional

    Parameter callback terlihat seperti: 

    ()=>void

Hasil

  • Promise<void>

    Chrome 96 dan yang lebih baru

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.

stopPinRequest()

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

Menghentikan permintaan penyematan yang dimulai oleh fungsi requestPin.

Parameter

  • Berisi detail tentang alasan penghentian alur permintaan.

  • callback

    fungsi opsional

    Parameter callback terlihat seperti: 

    ()=>void

Hasil

  • Promise<void>

    Chrome 96 dan yang lebih baru

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.

Peristiwa

onCertificatesRequested

Chrome 47+ &leq; MV2 Tidak digunakan lagi sejak Chrome 86
chrome.certificateProvider.onCertificatesRequested.addListener(
  callback: function,
)

Sebagai gantinya, gunakan onCertificatesUpdateRequested.

Peristiwa ini aktif setiap kali browser meminta daftar sertifikat saat ini yang disediakan oleh ekstensi ini. Ekstensi harus memanggil reportCallback tepat sekali dengan daftar sertifikat saat ini.

Parameter

  • callback

    fungsi

    Parameter callback terlihat seperti: 

    (reportCallback: function)=>void

    • reportCallback

      fungsi

      Parameter reportCallback terlihat seperti: 

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

      • sertifikat

        CertificateInfo[]

      • callback

        fungsi

        Parameter callback terlihat seperti: 

        (rejectedCertificates: ArrayBuffer[])=>void

        • rejectedCertificates

          ArrayBuffer[]

onCertificatesUpdateRequested

Chrome 86 dan yang lebih baru 
chrome.certificateProvider.onCertificatesUpdateRequested.addListener(
  callback: function,
)

Peristiwa ini aktif jika sertifikat yang ditetapkan melalui setCertificates tidak memadai atau browser meminta informasi yang diperbarui. Ekstensi harus memanggil setCertificates dengan daftar sertifikat yang diperbarui dan certificatesRequestId yang diterima.

Parameter

onSignatureRequested

Chrome 86 dan yang lebih baru 
chrome.certificateProvider.onSignatureRequested.addListener(
  callback: function,
)

Peristiwa ini aktif setiap kali browser perlu menandatangani pesan menggunakan sertifikat yang disediakan oleh ekstensi ini melalui setCertificates.

Ekstensi harus menandatangani data input dari request menggunakan algoritma dan kunci pribadi yang sesuai, lalu menampilkannya dengan memanggil reportSignature dengan signRequestId yang diterima.

Parameter

onSignDigestRequested

&leq; MV2 Tidak digunakan lagi sejak Chrome 86
chrome.certificateProvider.onSignDigestRequested.addListener(
  callback: function,
)

Sebagai gantinya, gunakan onSignatureRequested.

Peristiwa ini aktif setiap kali browser perlu menandatangani pesan menggunakan sertifikat yang disediakan oleh ekstensi ini sebagai balasan terhadap peristiwa onCertificatesRequested. Ekstensi harus menandatangani data di request menggunakan algoritma dan kunci pribadi yang sesuai, lalu menampilkannya dengan memanggil reportCallback. reportCallback harus dipanggil tepat sekali.

Parameter

  • callback

    fungsi

    Parameter callback terlihat seperti: 

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

    • minta

      SignRequest

    • reportCallback

      fungsi

      Chrome 47+

      Parameter reportCallback terlihat seperti: 

      (signature?: ArrayBuffer)=>void

      • tanda tangan

        ArrayBuffer opsional