Deskripsi
Gunakan API ini untuk mengekspos sertifikat ke platform yang dapat menggunakan sertifikat ini untuk autentikasi TLS.
Izin
certificateProvider
Ketersediaan
Konsep dan penggunaan
Penggunaan standar API ini untuk mengekspos sertifikat klien ke ChromeOS mengikuti langkah-langkah berikut:
- Ekstensi didaftarkan untuk peristiwa
onCertificatesUpdateRequested
danonSignatureRequested
. - 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 akan 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 tersedia saat ini, menggunakan metode
setCertificates()
. - Browser mencocokkan semua sertifikat yang tersedia dengan permintaan sertifikat klien dari host jarak jauh. Kecocokan ditampilkan kepada pengguna dalam dialog pilihan.
- Pengguna dapat memilih sertifikat dan dengan demikian menyetujui atau membatalkan autentikasi.
![Dialog pemilihan sertifikat](https://developer.chrome.google.cn/static/docs/extensions/reference/api/images/certificate_provider_selection_dialog.png?authuser=0000&hl=id)
- 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 algoritme mana yang harus digunakan untuk membuat tanda tangan, dan merujuk ke salah satu sertifikat yang dilaporkan oleh Ekstensi ini. Ekstensi harus membuat tanda tangan untuk data yang diberikan menggunakan kunci pribadi yang terkait dengan sertifikat yang direferensikan. Membuat tanda tangan mungkin memerlukan penambahan DigestInfo dan padding 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 menyelesaikan handshake TLS.
Urutan langkah yang sebenarnya dapat berbeda. Misalnya, pengguna tidak akan diminta untuk memilih sertifikat jika kebijakan perusahaan untuk memilih sertifikat secara otomatis digunakan (lihat AutoSelectCertificateForUrls
dan kebijakan Chrome untuk pengguna).
Di Ekstensi, hal ini dapat terlihat mirip dengan cuplikan 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
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 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 dimintai tanda tangan ringkasan yang dihitung dengan salah satu algoritma hash ini. Langkah ini harus dilakukan dengan urutan penurunan preferensi hash.
CertificatesUpdateRequest
Properti
-
certificatesRequestId
angka
Minta ID untuk diteruskan ke
setCertificates
.
ClientCertificateInfo
Properti
-
certificateChain
ArrayBuffer[]
Array harus berisi encoding DER sertifikat klien X.509 sebagai elemen pertamanya.
Sertifikat harus menyertakan tepat satu sertifikat.
-
supportedAlgorithms
Semua algoritma didukung untuk sertifikat ini. Ekstensi hanya akan diminta tanda tangan menggunakan salah satu algoritma ini.
Error
Jenis error yang dapat dilaporkan oleh ekstensi.
Nilai
"UMUM_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
Jenis error yang dapat ditampilkan kepada pengguna melalui fungsi requestPin.
Enum
"INVALID_PIN"
Penentuan PIN tidak valid.
"INVALID_PUK"
Menentukan PUK tidak valid.
"MAX_GIVENS_EXCEEDED"
Menentukan jumlah upaya maksimum telah terlampaui.
"UNKNOWN_ERROR"
Menentukan bahwa error tidak dapat ditunjukkan oleh jenis di atas.
PinRequestType
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
Properti
-
userInput
string opsional
Kode yang diberikan oleh pengguna. Kosong jika pengguna menutup dialog atau terjadi beberapa error lain.
ReportSignatureDetails
Properti
-
error
"UMUM_ERROR"
opsionalKesalahan yang terjadi saat membuat tanda tangan, jika ada.
-
signRequestId
angka
ID permintaan yang diterima melalui peristiwa
onSignatureRequested
. -
tanda tangan
ArrayBuffer opsional
Tanda tangan, jika berhasil dibuat.
RequestPinDetails
Properti
-
attemptsLeft
angka opsional
Jumlah percobaan yang tersisa. Ini disediakan sehingga setiap UI dapat menyajikan informasi ini kepada pengguna. Chrome tidak diharapkan untuk menerapkan hal ini, sebagai gantinya stopPinRequest harus dipanggil oleh ekstensi dengan errorType = MAX_GIVENS_EXCEEDED saat jumlah permintaan PIN terlampaui.
-
errorType
PinRequestErrorType optional
Template error yang ditampilkan kepada pengguna. Kunci ini harus disetel jika permintaan sebelumnya gagal, untuk memberi tahu pengguna tentang alasan kegagalan.
-
requestType
PinRequestType opsional
Jenis kode yang diminta. Defaultnya adalah PIN.
-
signRequestId
angka
ID yang diberikan oleh Chrome di SignRequest.
SetCertificatesDetails
Properti
-
certificatesRequestId
angka opsional
Saat dipanggil sebagai respons terhadap
onCertificatesUpdateRequested
, harus berisi nilaicertificatesRequestId
yang diterima. Jika tidak, harus dibatalkan penetapannya. -
clientCertificates
Daftar sertifikat klien yang saat ini tersedia.
-
error
"UMUM_ERROR"
opsionalError yang terjadi saat mengekstrak sertifikat, jika ada. Error ini akan ditampilkan kepada pengguna jika diperlukan.
SignatureRequest
Properti
-
algoritme
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
Mengacu pada algoritma hash yang digunakan untuk membuat
digest
. -
signRequestId
angka
Chrome 57 dan yang lebih baruID unik yang akan digunakan oleh ekstensi jika perlu memanggil metode yang memerlukannya, mis. {i>requestPin<i}.
StopPinRequestDetails
Properti
-
errorType
PinRequestErrorType optional
Template error. Jika ada, data akan ditampilkan kepada pengguna. Dimaksudkan untuk menyertakan alasan penghentian aliran jika disebabkan oleh kesalahan, mis. MAX_GIVENS_EXCEEDED.
-
signRequestId
angka
ID yang diberikan oleh Chrome di SignRequest.
Metode
reportSignature()
chrome.certificateProvider.reportSignature(
details: ReportSignatureDetails,
callback?: function,
)
Harus dipanggil sebagai respons terhadap onSignatureRequested
.
Ekstensi akhirnya 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
-
detail
-
callback
fungsi opsional
Parameter
callback
terlihat seperti ini:() => void
Hasil
-
Janji<void>
Chrome 96 dan yang lebih baruPromise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.
requestPin()
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
-
detail
Berisi detail tentang dialog yang diminta.
-
callback
fungsi opsional
Parameter
callback
terlihat seperti ini:(details?: PinResponseDetails) => void
-
detail
PinResponseDetails opsional
-
Hasil
-
Promise<PinResponseDetails | tidak terdefinisi>
Chrome 96 dan yang lebih baruPromise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.
setCertificates()
chrome.certificateProvider.setCertificates(
details: SetCertificatesDetails,
callback?: function,
)
Menetapkan daftar sertifikat yang akan 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
-
detail
Sertifikat yang akan ditetapkan. Sertifikat yang tidak valid akan diabaikan.
-
callback
fungsi opsional
Parameter
callback
terlihat seperti ini:() => void
Hasil
-
Janji<void>
Chrome 96 dan yang lebih baruPromise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.
stopPinRequest()
chrome.certificateProvider.stopPinRequest(
details: StopPinRequestDetails,
callback?: function,
)
Menghentikan permintaan pin yang dimulai oleh fungsi requestPin
.
Parameter
-
detail
Berisi detail tentang alasan penghentian alur permintaan.
-
callback
fungsi opsional
Parameter
callback
terlihat seperti ini:() => void
Hasil
-
Janji<void>
Chrome 96 dan yang lebih baruPromise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.
Acara
onCertificatesRequested
chrome.certificateProvider.onCertificatesRequested.addListener(
callback: function,
)
Sebagai gantinya, gunakan onCertificatesUpdateRequested
.
Peristiwa ini diaktifkan setiap kali browser meminta daftar sertifikat saat ini yang disediakan oleh ekstensi ini. Ekstensi harus memanggil reportCallback
tepat satu kali dengan daftar sertifikat saat ini.
Parameter
-
callback
fungsi
Parameter
callback
terlihat seperti ini:(reportCallback: function) => void
-
reportCallback
fungsi
Parameter
reportCallback
terlihat seperti ini:(certificates: CertificateInfo[], callback: function) => void
-
sertifikat
-
callback
fungsi
Parameter
callback
terlihat seperti ini:(rejectedCertificates: ArrayBuffer[]) => void
-
rejectedCertificates
ArrayBuffer[]
-
-
-
onCertificatesUpdateRequested
chrome.certificateProvider.onCertificatesUpdateRequested.addListener(
callback: function,
)
Peristiwa ini diaktifkan 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
-
callback
fungsi
Parameter
callback
terlihat seperti ini:(request: CertificatesUpdateRequest) => void
onSignatureRequested
chrome.certificateProvider.onSignatureRequested.addListener(
callback: function,
)
Peristiwa ini diaktifkan setiap kali browser perlu menandatangani pesan menggunakan sertifikat yang diberikan oleh ekstensi ini melalui setCertificates
.
Ekstensi harus menandatangani data input dari request
menggunakan algoritma dan kunci pribadi yang sesuai dan menampilkannya dengan memanggil reportSignature
dengan signRequestId
yang diterima.
Parameter
-
callback
fungsi
Parameter
callback
terlihat seperti ini:(request: SignatureRequest) => void
-
minta
-
onSignDigestRequested
chrome.certificateProvider.onSignDigestRequested.addListener(
callback: function,
)
Sebagai gantinya, gunakan onSignatureRequested
.
Peristiwa ini diaktifkan setiap kali browser perlu menandatangani pesan menggunakan sertifikat yang diberikan oleh ekstensi ini sebagai balasan atas peristiwa onCertificatesRequested
. Ekstensi harus menandatangani data dalam request
menggunakan algoritma dan kunci pribadi yang sesuai, serta menampilkannya dengan memanggil reportCallback
. reportCallback
harus dipanggil tepat satu kali.
Parameter
-
callback
fungsi
Parameter
callback
terlihat seperti ini:(request: SignRequest, reportCallback: function) => void
-
minta
-
reportCallback
fungsi
Chrome 47 dan yang lebih baruParameter
reportCallback
terlihat seperti ini:(signature?: ArrayBuffer) => void
-
tanda tangan
ArrayBuffer opsional
-
-