chrome.platformKeys

說明

使用 chrome.platformKeys API 存取平台管理的用戶端憑證。如果使用者或政策授予權限,擴充功能就能在自訂驗證通訊協定中使用這類憑證。例如:這允許在第三方 VPN 中使用平台管理的憑證 (請參閱 chrome.vpnProvider)。

權限

platformKeys

可用性

Chrome 45 以上版本 僅適用於 ChromeOS

類型

ClientCertificateRequest

屬性

  • certificateAuthorities

    ArrayBuffer[]

    伺服器允許的憑證授權單位辨別名稱清單。每個項目都必須是 DER 編碼的 X.509 DistinguishedName。

  • certificateTypes

    這個欄位會列出要求的憑證類型,並按照伺服器偏好設定排序。系統只會擷取這份清單中的類型憑證。不過,如果 certificateTypes 是空白清單,則會傳回任何類型的憑證。

ClientCertificateType

列舉

"rsaSign"

"ecdsaSign"

Match

屬性

  • 認證

    ArrayBuffer

    X.509 憑證的 DER 編碼。

  • keyAlgorithm

    物件

    認證金鑰的 KeyAlgorithm。其中包含的是憑證金鑰固有的演算法參數 (例如金鑰長度)。不含正負號函式使用的雜湊函式等其他參數。

SelectDetails

屬性

  • clientCerts

    ArrayBuffer[] 選用

    如果指定,selectClientCertificates 會在此清單中運作。如果不是,則從平台的憑證存放區取得可用於這個擴充功能的所有憑證清單。系統會移除擴充功能不具備權限或不符合要求的項目。

  • 互動

    布林值

    如果設為 true,系統會向使用者顯示篩選後的清單,讓使用者手動選取憑證,並授權擴充功能存取憑證和金鑰。系統只會傳回選取的憑證。設為 false 時,清單縮小為自動或手動授權有權存取的所有憑證。

  • 系統只會傳回符合這項要求的憑證。

VerificationDetails

屬性

  • 主機名稱

    字串

    驗證憑證的伺服器主機名稱,例如提供 serverCertificateChain 的伺服器。

  • serverCertificateChain

    ArrayBuffer[]

    每個鏈結項目都必須使用 X.509 憑證的 DER 編碼,第一個項目必須是伺服器憑證,且每個項目都必須對其前面的項目進行認證。

VerificationResult

屬性

  • debug_errors

    string[]

    如果信任驗證失敗,這個陣列會包含基礎網路層回報的錯誤。否則,這個陣列是空的。

    注意:這份清單僅供偵錯之用,不一定包含所有相關錯誤。系統傳回的錯誤可能在未來的這個 API 修訂版本中有所變更,而且不保證與先前版本相容。

  • 可信任

    布林值

    信任驗證結果:如果系統可以建立驗證作業詳細資料的信任,則為 true;如果信任因任何原因而遭拒,則為 false。

方法

getKeyPair()

chrome.platformKeys.getKeyPair(
  certificate: ArrayBuffer,
  parameters: object,
  callback: function,
)

certificate 的金鑰組傳送至 callback,以便使用 platformKeys.subtleCrypto

參數

  • 認證

    ArrayBuffer

    selectClientCertificates 傳回的 Match 憑證。

  • parameters

    物件

    除了依據金鑰本身固定的參數之外,決定簽章/雜湊演算法參數。WebCrypto 的 importKey 函式接受相同的參數,例如:RsaHashedImportParams 用於 RSASSA-PKCS1-v1_5 金鑰,EcKeyImportParams 用於 EC 金鑰。此外,如果是 RSASSA-PKCS1-v1_5 鍵,可以使用下列任一值指定雜湊演算法名稱參數:「none」、「SHA-1」、「SHA-256」、「SHA-384」或「SHA-512」,例如{"hash": { "name": "none" } }。然後,符號函式會套用 PKCS#1 v1.5 邊框間距,但不會對指定資料進行雜湊處理。

    這個方法目前僅支援「RSASSA-PKCS1-v1_5」和「ECDSA」演算法。

  • 回呼

    函式

    callback 參數如下所示:

    (publicKey: object, privateKey?: object) => void

    • publicKey

      物件

    • privateKey

      物件 optional

      如果這個擴充功能沒有存取權,就可能是 null

getKeyPairBySpki()

Chrome 85 以上版本
chrome.platformKeys.getKeyPairBySpki(
  publicKeySpkiDer: ArrayBuffer,
  parameters: object,
  callback: function,
)

publicKeySpkiDer 識別的金鑰組傳遞至 callback,以使用 platformKeys.subtleCrypto

參數

  • publicKeySpkiDer

    ArrayBuffer

    取得 DER 編碼的 X.509 SubjectPublicKeyInfo,例如:使用 format="spki" 呼叫 WebCrypto 的 exportKey 函式。

  • parameters

    物件

    提供簽章和雜湊演算法參數,以及由金鑰本身固定的參數。WebCrypto 的 importKey 函式接受相同的參數,例如:RsaHashedImportParams 適用於 RSASSA-PKCS1-v1_5 金鑰。如果是 RSASSA-PKCS1-v1_5 金鑰,我們也需傳送「雜湊」參數 { "hash": { "name": string } }。「雜湊」參數代表在符號前面,摘要作業中使用的雜湊演算法名稱。您可以將「無」做為雜湊名稱,此時,符號函式會套用 PKCS#1 v1.5 邊框間距,但不會對指定資料進行雜湊處理。

    這個方法目前支援「ECDSA」將演算法設為具有名字的曲線 P-256 和「RSASSA-PKCS1-v1_5」,將演算法與其中一個雜湊演算法搭配使用:「none」、「SHA-1」、「SHA-256」、「SHA-384」和「SHA-512」。

  • 回呼

    函式

    callback 參數如下所示:

    (publicKey: object, privateKey?: object) => void

    • publicKey

      物件

    • privateKey

      物件 optional

      如果這個擴充功能沒有存取權,就可能是 null

selectClientCertificates()

Promise
chrome.platformKeys.selectClientCertificates(
  details: SelectDetails,
  callback?: function,
)

這個方法會從平台已知的用戶端憑證清單中篩選,比對 request,且擴充功能可存取憑證及其私密金鑰的權限。如果 interactive 為 true,系統會向使用者顯示對話方塊,讓他們從相符的憑證中選取,並授予擴充功能存取憑證的權限。所選/篩選的用戶端憑證會傳遞至 callback

參數

  • 詳細資料
  • 回呼

    函式 選用

    callback 參數如下所示:

    (matches: Match[]) => void

    • 完全相符

      與要求相符的憑證清單、擴充功能擁有權限;如果 interactive 為 true,則由使用者選取的憑證清單。

傳回

  • 承諾<相符[]>

    Chrome 121 以上版本

    Promise 僅適用於 Manifest V3 及以上版本,其他平台需要使用回呼。

subtleCrypto()

chrome.platformKeys.subtleCrypto()

實作 WebCrypto 的 SubtleCrypto,允許對適用於這個擴充功能的用戶端憑證的金鑰進行加密作業。

傳回

  • object |未定義

verifyTLSServerCertificate()

Promise
chrome.platformKeys.verifyTLSServerCertificate(
  details: VerificationDetails,
  callback?: function,
)

根據平台的信任設定,檢查 details.serverCertificateChain 是否可信任 details.hostname。注意:信任驗證的實際行為並未完整指定,而且日後可能會有變動。API 實作會驗證憑證有效期限、驗證憑證路徑,並檢查已知 CA 的信任。實作時應遵循 EKU 伺服器驗證,並支援主體別名。

參數

傳回

  • Promise&lt;VerificationResult&gt;

    Chrome 121 以上版本

    Promise 僅適用於 Manifest V3 及以上版本,其他平台需要使用回呼。