說明
請使用這個 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 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
requestPin()
chrome.certificateProvider.requestPin(
details: RequestPinDetails,
callback?: function,
)
要求使用者提供 PIN。系統一次只能持續執行一項要求。在其他流程進行期間發出的要求會遭到拒絕。如果其他流程正在執行,擴充功能有責任再試一次。
參數
-
詳細資料
包含要求對話方塊的詳細資料。
-
回呼
函式選用
callback
參數如下所示:(details?: PinResponseDetails) => void
-
詳細資料
-
傳回
-
Promise<PinResponseDetails | undefined>
Chrome 96 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
setCertificates()
chrome.certificateProvider.setCertificates(
details: SetCertificatesDetails,
callback?: function,
)
設定在瀏覽器中使用的憑證清單。
完成初始化後,以及每當目前可用憑證組合中的變更,擴充功能都應呼叫此函式。擴充功能也應在每次收到這個事件時呼叫此函式來回應 onCertificatesUpdateRequested
。
參數
-
要設定的憑證。系統會忽略無效的憑證。
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 96 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
stopPinRequest()
chrome.certificateProvider.stopPinRequest(
details: StopPinRequestDetails,
callback?: function,
)
停止 requestPin
函式啟動的圖釘要求。
參數
-
包含停止要求流程的原因詳細資料。
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<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 選用
-
-