說明
請使用這個 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 邊框間距。這個演算法已淘汰，自 109 版起一律不會要求 Chrome 要求。
"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"
使用 SHA-256 雜湊函式、MGF1 遮罩產生函式和與雜湊大小相同的鹽，指定 RSASSA PSS 簽名演算法。
"RSASSA_PSS_SHA384"
使用 SHA-384 雜湊函式、MGF1 遮罩產生函式和與雜湊大小相同的鹽，指定 RSASSA PSS 簽名演算法。
"RSASSA_PSS_SHA512"
使用 SHA-512 雜湊函式、MGF1 遮罩產生函式和與雜湊大小相同的鹽，指定 RSASSA PSS 簽名演算法。
CertificateInfo
屬性
-
認證
ArrayBuffer
必須是 X.509 憑證的 DER 編碼。目前僅支援 RSA 金鑰憑證。
-
supportedHashes
雜湊[]
必須設為這個憑證支援的所有雜湊。這個擴充功能只會要求系統使用其中一種雜湊演算法計算的摘要簽章。請根據降低雜湊偏好設定的數量。
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 碼是 PIN 碼。
「PUK」
指定要求的代碼是 PUK。
PinResponseDetails
屬性
-
userInput
string optional
使用者提供的代碼。如果使用者關閉對話方塊或發生其他錯誤，則為空白。
ReportSignatureDetails
屬性
-
錯誤
"GENERAL_ERROR"
選用產生簽章時發生錯誤 (如有)。
-
signRequestId
數字
透過
onSignatureRequested事件接收的要求 ID。 -
簽名
ArrayBuffer 選用
簽章 (如果成功產生)。
RequestPinDetails
屬性
-
attemptsLeft
編號 選填
剩餘嘗試次數。這種做法可確保任何 UI 都能向使用者顯示這項資訊。Chrome 不會強制執行這項限制，一旦超過 PIN 碼要求數量，擴充功能就必須呼叫 stopPinRequest (errorType = MAX_ATTEMPTS_EXCEEDED)。
-
errorType
PinRequestErrorType optional
向使用者顯示的錯誤範本。如果先前的要求失敗，則應設定此值，通知使用者失敗原因。
-
requestType
要求的代碼類型。預設值為 PIN 碼。
-
signRequestId
數字
Chrome in SignRequest 提供的 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。
StopPinRequestDetails
屬性
-
errorType
PinRequestErrorType optional
錯誤範本。如果有向使用者顯示。包含因錯誤造成資料流停止的原因，例如MAX_ATTEMPTS_EXCEEDED。
-
signRequestId
數字
Chrome in SignRequest 提供的 ID。
方法
reportSignature()
chrome.certificateProvider.reportSignature(
details: ReportSignatureDetails,
callback?: function,
)
應呼叫為對 onSignatureRequested 的回應。
擴充功能最終必須針對每個 onSignatureRequested 事件呼叫此函式；API 實作方式會在一段時間後停止等待此呼叫，並在呼叫此函式時回應逾時錯誤。
參數
-
回呼
函式 選用
callback參數如下所示：() => void
傳回
-
承諾<void>
Chrome 96 以上版本Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。
requestPin()
chrome.certificateProvider.requestPin(
details: RequestPinDetails,
callback?: function,
)
要求使用者提供 PIN。一次只能處理一項要求。其他流程持續執行時發出的要求會遭到拒絕。如果正在執行其他流程，擴充功能會負責稍後再試一次。
參數
-
詳細資料
包含所要求對話方塊的詳細資料。
-
回呼
函式 選用
callback參數如下所示：(details?: PinResponseDetails) => void
-
詳細資料
-
傳回
-
Promise<PinResponseDetails |未定義>
Chrome 96 以上版本Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。
setCertificates()
chrome.certificateProvider.setCertificates(
details: SetCertificatesDetails,
callback?: function,
)
設定要在瀏覽器中使用的憑證清單。
此擴充功能應會在初始化之後，以及目前可用憑證集中的每個變更時呼叫此函式。擴充功能也應在每次接收到這個事件時，呼叫此函式來回應 onCertificatesUpdateRequested。
參數
-
要設定的憑證。系統會忽略無效的憑證。
-
回呼
函式 選用
callback參數如下所示：() => void
傳回
-
承諾<void>
Chrome 96 以上版本Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。
stopPinRequest()
chrome.certificateProvider.stopPinRequest(
details: StopPinRequestDetails,
callback?: function,
)
停止 requestPin 函式啟動的 PIN 要求。
參數
-
包含停止要求流程的原因詳細資料。
-
回呼
函式 選用
callback參數如下所示：() => void
傳回
-
承諾<void>
Chrome 96 以上版本Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。
活動
onCertificatesRequested
chrome.certificateProvider.onCertificatesRequested.addListener(
callback: function,
)
請改用 onCertificatesUpdateRequested。
每次瀏覽器要求此擴充功能提供的目前憑證清單時，就會觸發這個事件。擴充功能必須使用目前的憑證清單明確呼叫 reportCallback 一次。
參數
-
回呼
函式
callback參數如下所示：(reportCallback: function) => void
-
reportCallback
函式
reportCallback參數如下所示：(certificates: CertificateInfo[], callback: function) => void
-
certificates
-
回呼
函式
callback參數如下所示：(rejectedCertificates: ArrayBuffer[]) => void
-
rejectedCertificates
ArrayBuffer[]
-
-
-
onCertificatesUpdateRequested
chrome.certificateProvider.onCertificatesUpdateRequested.addListener(
callback: function,
)
如果透過 setCertificates 設定的憑證不足，或瀏覽器要求更新的資訊，就會觸發這個事件。擴充功能必須使用更新後的憑證清單和已收到的 certificatesRequestId 呼叫 setCertificates。
參數
-
回呼
函式
callback參數如下所示：(request: CertificatesUpdateRequest) => void
onSignatureRequested
chrome.certificateProvider.onSignatureRequested.addListener(
callback: function,
)
每當瀏覽器需要使用這個擴充功能透過 setCertificates 提供的憑證簽署訊息時，就會觸發這個事件。
擴充功能必須使用適當的演算法和私密金鑰簽署 request 的輸入資料，再使用收到的 signRequestId 呼叫 reportSignature 來傳回資料。
參數
-
回呼
函式
callback參數如下所示：(request: SignatureRequest) => void
-
申請。
-
onSignDigestRequested
chrome.certificateProvider.onSignDigestRequested.addListener(
callback: function,
)
請改用 onSignatureRequested。
每當瀏覽器需要使用這個擴充功能提供的憑證簽署訊息，才能回覆 onCertificatesRequested 事件時，就會觸發這個事件。擴充功能必須使用適當的演算法和私密金鑰在 request 中簽署資料，然後呼叫 reportCallback 傳回資料。reportCallback 只能呼叫一次。
參數
-
回呼
函式
callback參數如下所示：(request: SignRequest, reportCallback: function) => void
-
申請。
-
reportCallback
函式
Chrome 47 以上版本reportCallback參數如下所示：(signature?: ArrayBuffer) => void
-
簽名
ArrayBuffer 選用
-
-