說明
請使用這個 API 向平台公開憑證，讓該平台使用這些憑證執行傳輸層安全標準 (TLS) 驗證。
權限
certificateProvider適用國家/地區
概念和用法
向 ChromeOS 公開用戶端憑證的一般用途時，使用這個 API 的常見用途：
- 擴充功能會註冊
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"
使用 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
擴充功能可回報的錯誤類型。
值
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
屬性
-
錯誤
選用
產生簽名時發生錯誤 (如果有的話)。
-
signRequestId
號碼
透過
onSignatureRequested事件收到的要求 ID。 -
簽名
ArrayBuffer 選用
簽章 (如果成功產生)。
RequestPinDetails
屬性
-
attemptsLeft
數字 選填
剩餘嘗試次數。這樣一來，所有 UI 都能向使用者顯示這項資訊。Chrome 不會強制執行這項操作，如果超過 PIN 要求數量，擴充功能應呼叫 stopPinRequest 為 errorType = MAX_ATTEMPTS_EXCEEDED。
-
errorType
向使用者顯示的錯誤範本。如果先前的要求失敗，則應設定這個值，以便通知使用者失敗原因。
-
requestType
要求的驗證碼類型。預設值為 PIN 碼。
-
signRequestId
號碼
Chrome 在 SignRequest 中提供的 ID。
SetCertificatesDetails
屬性
-
certificatesRequestId
數字 選填
呼叫
onCertificatesUpdateRequested時，應包含收到的certificatesRequestId值。否則應取消設定。 -
clientCertificates
目前可用的用戶端憑證清單。
-
錯誤
選用
擷取憑證時發生錯誤 (如果有的話)。這項錯誤會適時向使用者顯示。
SignatureRequest
屬性
-
演算法
要使用的簽章演算法。
-
認證
ArrayBuffer
X.509 憑證的 DER 編碼。擴充功能必須使用相關聯的私密金鑰簽署
input。 -
輸入
ArrayBuffer
要簽署的資料。請注意，資料未經雜湊處理。
-
signRequestId
號碼
要傳遞至
reportSignature的要求 ID。
SignRequest
屬性
-
認證
ArrayBuffer
X.509 憑證的 DER 編碼。擴充功能必須使用相關聯的私密金鑰簽署
digest。 -
摘要
ArrayBuffer
必須簽署的摘要。
-
hash
意指用於建立
digest的雜湊演算法。 -
signRequestId
號碼
Chrome 57 以上版本擴充功能要使用的專屬 ID，必須是擴充功能呼叫的方法，例如 requestPin。
StopPinRequestDetails
屬性
-
errorType
錯誤範本。(如有顯示)。如果錯誤是因錯誤而造成流程停止，其目的為包含停止流程的原因，例如 MAX_ATTEMPTS_EXCEEDED。
-
signRequestId
號碼
Chrome 在 SignRequest 中提供的 ID。
方法
reportSignature()
chrome.certificateProvider.reportSignature(
details: ReportSignatureDetails,
callback?: function,
)
應呼叫為 onSignatureRequested 的回應。
擴充功能最終必須為每個 onSignatureRequested 事件呼叫這個函式；API 實作項目會在一段時間後停止等待此呼叫，並在呼叫這個函式時傳回逾時錯誤。
參數
-
回呼
函式選用
callback參數如下所示：()=>void
傳回
-
Promise<void>
Chrome 96 以上版本Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
requestPin()
chrome.certificateProvider.requestPin(
details: RequestPinDetails,
callback?: function,
)
要求使用者提供 PIN。系統一次只能持續執行一項要求。在其他流程進行期間發出的要求會遭到拒絕。如果其他流程正在執行，擴充功能有責任再試一次。
參數
-
詳細資料
包含要求對話方塊的詳細資料。
-
回呼
函式選用
callback參數如下所示：(details?: PinResponseDetails)=>void
-
詳細資料
-
傳回
-
Promise<PinResponseDetails|undefined>
Chrome 96 以上版本Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
setCertificates()
chrome.certificateProvider.setCertificates(
details: SetCertificatesDetails,
callback?: function,
)
設定在瀏覽器中使用的憑證清單。
完成初始化後，以及每當目前可用憑證組合中的變更，擴充功能都應呼叫此函式。擴充功能也應在每次收到這個事件時呼叫此函式來回應 onCertificatesUpdateRequested。
參數
-
要設定的憑證。系統會忽略無效的憑證。
-
回呼
函式選用
callback參數如下所示：()=>void
傳回
-
Promise<void>
Chrome 96 以上版本Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
stopPinRequest()
chrome.certificateProvider.stopPinRequest(
details: StopPinRequestDetails,
callback?: function,
)
停止 requestPin 函式啟動的圖釘要求。
參數
-
包含停止要求流程的原因詳細資料。
-
回呼
函式選用
callback參數如下所示：()=>void
傳回
-
Promise<void>
Chrome 96 以上版本Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
活動
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 選用
-
-