chrome.certificateProvider

說明

使用這個 API 將憑證公開給平台，讓平台可用這些憑證進行 TLS 驗證。

權限

certificateProvider

可用性

Chrome 46 以上版本 (僅限 ChromeOS)

用量

這個 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

Chrome 86 以上版本

系統支援的加密編譯簽章演算法類型。

列舉

"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

Chrome 86 以上版本

屬性

  • certificatesRequestId

    數字

    要傳遞至 setCertificates 的要求 ID。

ClientCertificateInfo

Chrome 86 以上版本

屬性

  • certificateChain

    ArrayBuffer[]

    陣列必須包含 X.509 用戶端憑證的 DER 編碼，做為第一個元素。

    這項資訊必須包含一個憑證。

  • supportedAlgorithms

    演算法[]

    此憑證支援的所有演算法。擴充功能只會使用其中一種演算法要求簽名。

Error

Chrome 86 以上版本

擴充功能可回報的錯誤類型。

值

"GENERAL_ERROR"

Hash

已淘汰，已由 Algorithm 取代。

列舉

"MD5_SHA1"
指定 MD5 和 SHA1 雜湊演算法。

"SHA1"
指定 SHA1 雜湊演算法。

"SHA256"
指定 SHA256 雜湊演算法。

"SHA384"
指定 SHA384 雜湊演算法。

"SHA512"
指定 SHA512 雜湊演算法。

PinRequestErrorType

Chrome 57 以上版本

可透過 requestPin 函式向使用者顯示的錯誤類型。

列舉

"INVALID_PIN"
指定 PIN 碼無效。

"INVALID_PUK"
指出 PUK 無效。

"MAX_ATTEMPTS_EXCEEDED"
指定嘗試次數已超出上限。

"UNKNOWN_ERROR"
指定錯誤無法以上述類型表示。

PinRequestType

Chrome 57 以上版本

透過 requestPin 函式，由擴充功能要求的程式碼類型。

列舉

"PIN"
指定要求的代碼為 PIN 碼。

"PUK"
指定要求的碼為 PUK。

PinResponseDetails

Chrome 57 以上版本

屬性

  • userInput

    string 選填

    使用者提供的程式碼。如果使用者關閉對話方塊或發生其他錯誤，則為空白。

ReportSignatureDetails

Chrome 86 以上版本

屬性

  • 錯誤

    "GENERAL_ERROR"
     選用

    產生簽名時發生的錯誤 (如果有)。

  • signRequestId

    數字

    透過 onSignatureRequested 事件收到的要求 ID。

  • 簽名

    ArrayBuffer 選填

    已成功產生的簽名。

RequestPinDetails

Chrome 57 以上版本

屬性

  • attemptsLeft

    號碼 選填

    剩餘嘗試次數。這項資訊可讓任何 UI 向使用者顯示資訊。Chrome 不會強制執行這項操作，而是在超出固定要求數量時，由擴充功能呼叫 stopPinRequest，並傳入 errorType = MAX_ATTEMPTS_EXCEEDED。

  • errorType

    PinRequestErrorType 選填

    向使用者顯示的錯誤範本。如果先前的請求失敗，則應設定此值，以便通知使用者失敗原因。

  • requestType

    PinRequestType 選填

    要求的代碼類型。預設值為 PIN。

  • signRequestId

    數字

    Chrome 在 SignRequest 中提供的 ID。

SetCertificatesDetails

Chrome 86 以上版本

屬性

  • certificatesRequestId

    號碼 選填

    在回應 onCertificatesUpdateRequested 時呼叫時，應包含收到的 certificatesRequestId 值。否則應設為未設定。

  • clientCertificates

    ClientCertificateInfo[]

    目前可用的用戶端憑證清單。

  • 錯誤

    "GENERAL_ERROR"
     選用

    擷取憑證時發生的錯誤 (如果有)。系統會在適當情況下向使用者顯示這項錯誤。

SignatureRequest

Chrome 86 以上版本

屬性

  • 演算法

    演算法

    要使用的簽名演算法。

  • 認證

    ArrayBuffer

    X.509 憑證的 DER 編碼。擴充功能必須使用相關聯的私密金鑰簽署 input。

  • 輸入

    ArrayBuffer

    要簽署的資料。請注意，資料並未經過雜湊處理。

  • signRequestId

    數字

    要傳遞至 reportSignature 的要求 ID。

SignRequest

屬性

  • 認證

    ArrayBuffer

    X.509 憑證的 DER 編碼。擴充功能必須使用相關聯的私密金鑰簽署 digest。

  • 摘要

    ArrayBuffer

    必須簽署的摘要。

  • hash

    雜湊

    指的是用於建立 digest 的雜湊演算法。

  • signRequestId

    數字

    Chrome 57 以上版本

    擴充功能需要呼叫需要此 ID 的方法 (例如 requestPin) 時，就會使用這個專屬 ID。

StopPinRequestDetails

Chrome 57 以上版本

屬性

  • errorType

    PinRequestErrorType 選填

    錯誤範本。如果有，則會向使用者顯示。若是因錯誤而停止流程，則可用於提供停止原因，例如 MAX_ATTEMPTS_EXCEEDED。

  • signRequestId

    數字

    Chrome 在 SignRequest 中提供的 ID。

方法

reportSignature()

Promise Chrome 86 以上版本 
chrome.certificateProvider.reportSignature(
  details: ReportSignatureDetails,
  callback?: function,
)

應在回應 onSignatureRequested 時呼叫。

擴充功能最終必須為每個 onSignatureRequested 事件呼叫此函式；API 實作項目會在一段時間後停止等待此呼叫，並在呼叫此函式時回應逾時錯誤。

參數

傳回

  • Promise<void>

    Chrome 96 以上版本

    承諾僅支援資訊清單 V3 以上版本，其他平台則需使用回呼。

requestPin()

Promise Chrome 57 以上版本 
chrome.certificateProvider.requestPin(
  details: RequestPinDetails,
  callback?: function,
)

要求使用者提供 PIN 碼。一次只能有一個進行中的要求。在其他流程進行中發出的請求會遭到拒絕。如果其他流程正在進行中，擴充功能必須負責稍後再試。

參數

傳回

  • Promise<PinResponseDetails | undefined>

    Chrome 96 以上版本

    承諾僅支援資訊清單 V3 以上版本，其他平台則需使用回呼。

setCertificates()

Promise Chrome 86 以上版本 
chrome.certificateProvider.setCertificates(
  details: SetCertificatesDetails,
  callback?: function,
)

設定要在瀏覽器中使用的憑證清單。

擴充功能應在初始化後，以及目前可用憑證集每次變更時呼叫此函式。每次收到此事件時，擴充功能也應呼叫此函式，以回應 onCertificatesUpdateRequested。

參數

  • 詳細資料

    SetCertificatesDetails

    要設定的憑證。系統會忽略無效的憑證。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    Chrome 96 以上版本

    承諾僅支援資訊清單 V3 以上版本，其他平台則需使用回呼。

stopPinRequest()

Promise Chrome 57 以上版本 
chrome.certificateProvider.stopPinRequest(
  details: StopPinRequestDetails,
  callback?: function,
)

停止由 requestPin 函式啟動的固定位置要求。

參數

  • 詳細資料

    StopPinRequestDetails

    包含停止要求流程的原因詳細資料。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    Chrome 96 以上版本

    承諾僅支援資訊清單 V3 以上版本，其他平台則需使用回呼。

活動

onCertificatesRequested

Chrome 47 以上版本 &leq; MV2 自 Chrome 86 版起已淘汰
chrome.certificateProvider.onCertificatesRequested.addListener(
  callback: function,
)

請改用 onCertificatesUpdateRequested。

每次瀏覽器要求這個擴充功能提供的目前憑證清單時，就會觸發這個事件。擴充功能必須使用目前的憑證清單，呼叫 reportCallback 一次。

參數

  • 回呼

    函式

    callback 參數如下所示： 

    (reportCallback: function) => void

    • reportCallback

      函式

      reportCallback 參數如下所示： 

      (certificates: CertificateInfo[], callback: function) => void

      • certificates

        CertificateInfo[]

      • 回呼

        函式

        callback 參數如下所示： 

        (rejectedCertificates: ArrayBuffer[]) => void

        • rejectedCertificates

          ArrayBuffer[]

onCertificatesUpdateRequested

Chrome 86 以上版本 
chrome.certificateProvider.onCertificatesUpdateRequested.addListener(
  callback: function,
)

如果透過 setCertificates 設定的憑證不足，或是瀏覽器要求更新資訊，就會觸發這項事件。擴充功能必須使用更新的憑證清單和收到的 certificatesRequestId 呼叫 setCertificates。

參數

onSignatureRequested

Chrome 86 以上版本 
chrome.certificateProvider.onSignatureRequested.addListener(
  callback: function,
)

每當瀏覽器需要透過 setCertificates 使用此擴充功能提供的憑證簽署訊息時，就會觸發此事件。

擴充功能必須使用適當的演算法和私密金鑰，為 request 的輸入資料簽署，並透過呼叫 reportSignature 和已收到的 signRequestId 傳回。

參數

onSignDigestRequested

&leq; MV2 自 Chrome 86 版起已淘汰
chrome.certificateProvider.onSignDigestRequested.addListener(
  callback: function,
)

請改用 onSignatureRequested。

每當瀏覽器需要使用此擴充功能提供的憑證簽署訊息，以回應 onCertificatesRequested 事件時，就會觸發此事件。外掛程式必須使用適當的演算法和私密金鑰，對 request 中的資料簽署，並透過呼叫 reportCallback 傳回。reportCallback 必須呼叫一次。

參數

  • 回呼

    函式

    callback 參數如下所示： 

    (request: SignRequest, reportCallback: function) => void

    • 申請。

      SignRequest

    • reportCallback

      函式

      Chrome 47 以上版本

      reportCallback 參數如下所示： 

      (signature?: ArrayBuffer) => void

      • 簽名

        ArrayBuffer 選填