說明
使用這個 API 將憑證公開給平台，平台即可使用這些憑證進行 TLS 驗證。
權限
certificateProvider可用性
概念與用途
使用這個 API 將用戶端憑證公開給 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 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"
：指定使用 MD5-SHA-1 雜湊的 RSASSA PKCS#1 v1.5 簽章演算法。擴充功能不得在開頭加上 DigestInfo 前置字元，只能新增 PKCS#1 填補。這項演算法已淘汰，Chrome 109 以上版本不會再要求使用。
"RSASSA_PKCS1_v1_5_SHA1"
指定使用 SHA-1 雜湊函式的 RSASSA PKCS#1 v1.5 簽章演算法。
"RSASSA_PKCS1_v1_5_SHA256"
指定使用 SHA-256 雜湊函式的 RSASSA PKCS#1 v1.5 簽章演算法。
"RSASSA_PKCS1_v1_5_SHA384"
指定使用 SHA-384 雜湊函式的 RSASSA PKCS#1 v1.5 簽章演算法。
"RSASSA_PKCS1_v1_5_SHA512"
指定使用 SHA-512 雜湊函式的 RSASSA PKCS#1 v1.5 簽章演算法。
「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
必須是 X.509 憑證的 DER 編碼。目前僅支援 RSA 金鑰憑證。
- supportedHashes
Hash[]
必須設為這個憑證支援的所有雜湊。這項擴充功能只會要求使用其中一種雜湊演算法計算摘要的簽章。這應按照雜湊偏好設定遞減順序排列。
CertificatesUpdateRequest
屬性
- certificatesRequestId
數字
要傳遞至
setCertificates的要求 ID。
ClientCertificateInfo
屬性
- certificateChain
ArrayBuffer[]
陣列的第一個元素必須包含 X.509 用戶端憑證的 DER 編碼。
其中必須包含一個憑證。
- supportedAlgorithms
這項憑證支援的所有演算法。擴充功能只會要求使用其中一種演算法簽署。
Error
擴充功能可回報的錯誤類型。
值
「GENERAL_ERROR」
Hash
已淘汰，已由 Algorithm 取代。
列舉
「MD5_SHA1」
指定 MD5 和 SHA1 雜湊演算法。
「SHA1」
指定 SHA1 雜湊演算法。
「SHA256」
指定 SHA256 雜湊演算法。
「SHA384」
指定 SHA384 雜湊演算法。
「SHA512」
指定 SHA512 雜湊演算法。
PinRequestErrorType
可透過 requestPin 函式向使用者顯示的錯誤類型。
列舉
「INVALID_PIN」
指定 PIN 碼無效。
「INVALID_PUK」
指定 PUK 無效。
「MAX_ATTEMPTS_EXCEEDED」
指定嘗試次數已達上限。
「UNKNOWN_ERROR」
表示錯誤無法以以上類型表示。
PinRequestType
擴充功能透過 requestPin 函式要求的代碼類型。
列舉
「PIN」
指定要求的代碼為 PIN 碼。
「PUK」
指定要求的代碼為 PUK。
PinResponseDetails
屬性
- userInput
字串 選填
使用者提供的程式碼。如果使用者關閉對話方塊或發生其他錯誤，則為空白。
ReportSignatureDetails
屬性
- 錯誤
"GENERAL_ERROR"
選用產生簽章時發生的錯誤 (如有)。
- signRequestId
數字
透過
onSignatureRequested事件收到的要求 ID。 - 簽名
ArrayBuffer 選填
如果成功產生簽章，則為該簽章。
RequestPinDetails
屬性
- attemptsLeft
號碼 選填
剩餘嘗試次數。提供這項資訊是為了讓任何 UI 都能向使用者顯示這項資訊。Chrome 不會強制執行這項操作，而是會在 PIN 碼要求次數超過上限時，由擴充功能呼叫 stopPinRequest，並將 errorType 設為 MAX_ATTEMPTS_EXCEEDED。
- errorType
PinRequestErrorType optional
向使用者顯示的錯誤範本。如果先前的要求失敗，請設定這項屬性，通知使用者失敗原因。
- requestType
要求的代碼類型。預設值為 PIN 碼。
- signRequestId
數字
SignRequest 中 Chrome 提供的 ID。
SetCertificatesDetails
屬性
- certificatesRequestId
號碼 選填
在回應
onCertificatesUpdateRequested時呼叫，應包含收到的certificatesRequestId值。否則應取消設定。 - clientCertificates
目前可用的用戶端憑證清單。
- 錯誤
"GENERAL_ERROR"
選用如果有的話，即為擷取憑證時發生的錯誤。系統會在適當情況下向使用者顯示這項錯誤。
SignatureRequest
屬性
- 演算法
要使用的簽章演算法。
- 認證
ArrayBuffer
X.509 憑證的 DER 編碼。擴充功能必須使用相關聯的私密金鑰簽署
input。 - 輸入
ArrayBuffer
要簽署的資料。請注意，資料不會經過雜湊處理。
- signRequestId
數字
要傳遞至
reportSignature的要求 ID。
SignRequest
屬性
- 認證
ArrayBuffer
X.509 憑證的 DER 編碼。擴充功能必須使用相關聯的私密金鑰簽署
digest。 - 摘要
ArrayBuffer
必須簽署的摘要。
- hash
指用於建立
digest的雜湊演算法。 - signRequestId
數字
Chrome 57 以上版本擴充功能使用的專屬 ID，如果需要呼叫需要此 ID 的方法 (例如 requestPin)，就會用到這個 ID。
StopPinRequestDetails
屬性
- errorType
PinRequestErrorType optional
錯誤範本。如有提供，系統會向使用者顯示。如果流程因錯誤而停止，這個欄位會包含停止原因，例如 MAX_ATTEMPTS_EXCEEDED。
- signRequestId
數字
SignRequest 中 Chrome 提供的 ID。
方法
reportSignature()
chrome.certificateProvider.reportSignature(
details: ReportSignatureDetails,
): Promise<void>
應做為 onSignatureRequested 的回應呼叫。
擴充功能最終必須針對每個 onSignatureRequested 事件呼叫此函式；API 實作會在一段時間後停止等待此呼叫，並在呼叫此函式時傳回逾時錯誤。
參數
傳回
-
Promise<void>
Chrome 96 以上版本
requestPin()
chrome.certificateProvider.requestPin(
details: RequestPinDetails,
): Promise<PinResponseDetails | undefined>
要求使用者提供 PIN 碼。一次只能有一項進行中的要求。如果其他流程正在進行中，系統會拒絕發出的要求。如果另一個流程正在進行中，擴充功能有責任稍後再試。
參數
- 詳細資料
包含所要求對話方塊的詳細資料。
傳回
-
Promise<PinResponseDetails | undefined>
Chrome 96 以上版本
setCertificates()
chrome.certificateProvider.setCertificates(
details: SetCertificatesDetails,
): Promise<void>
設定要在瀏覽器中使用的憑證清單。
擴充功能應在初始化後，以及目前可用憑證組合的每次變更時，呼叫此函式。每當收到 onCertificatesUpdateRequested 事件時，擴充功能也應呼叫此函式。
參數
-
要設定的憑證。系統會忽略無效的憑證。
傳回
-
Promise<void>
Chrome 96 以上版本
stopPinRequest()
chrome.certificateProvider.stopPinRequest(
details: StopPinRequestDetails,
): Promise<void>
停止 requestPin 函式啟動的 PIN 碼要求。
參數
-
包含停止要求流程的原因詳細資料。
傳回
-
Promise<void>
Chrome 96 以上版本
事件
onCertificatesUpdateRequested
chrome.certificateProvider.onCertificatesUpdateRequested.addListener(
callback: function,
)
如果透過 setCertificates 設定的憑證不足，或瀏覽器要求更新資訊，就會觸發這個事件。擴充功能必須使用更新的憑證清單和收到的 certificatesRequestId 呼叫 setCertificates。
參數
- callback
函式
callback參數如下：(request: CertificatesUpdateRequest) => void
onSignatureRequested
chrome.certificateProvider.onSignatureRequested.addListener(
callback: function,
)
每當瀏覽器需要使用這個擴充功能透過 setCertificates 提供的憑證簽署訊息時，就會觸發這個事件。
擴充功能必須使用適當的演算法和私密金鑰簽署 request 中的輸入資料，並使用收到的 signRequestId 呼叫 reportSignature，傳回簽署的資料。
參數
- callback
函式
callback參數如下：(request: SignatureRequest) => void
- 申請。
-