chrome.platformKeys

說明

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

權限

platformKeys

適用國家/地區

Chrome 45 以上版本 僅限 ChromeOS

類型

ClientCertificateRequest

屬性

  • certificateAuthorities

    ArrayBuffer[]

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

  • certificateTypes

    ClientCertificateType[]

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

ClientCertificateType

列舉

"rsaSign"

"ecdsaSign"

Match

屬性

  • 認證

    ArrayBuffer

    X.509 憑證的 DER 編碼。

  • keyAlgorithm

    物件

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

SelectDetails

屬性

  • clientCerts

    ArrayBuffer[] 選用

    如果有指定，selectClientCertificates 就會根據這份清單運作。否則，請從平台的憑證存放區，取得可提供這個擴充功能的所有憑證清單。系統會移除擴充功能沒有權限或與要求不相符的項目。

  • interactive

    boolean

    如果設為 True，系統會向使用者顯示篩選清單，讓他們手動選取憑證，進而授予擴充功能和金鑰和金鑰的存取權。系統只會傳回所選憑證。設為 false 時，清單會縮減為已授予擴充功能存取權的所有憑證 (自動或手動)。

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

VerificationDetails

屬性

  • 主機名稱

    字串

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

  • serverCertificateChain

    ArrayBuffer[]

    每個鏈結項目都必須是 X.509 憑證的 DER 編碼，第一個項目必須是伺服器憑證，且每個項目都必須驗證其前面的項目。

VerificationResult

屬性

  • debug_errors

    string[]

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

    注意：這份清單僅供偵錯之用，可能不會包含所有相關錯誤。傳回的錯誤可能會在此 API 的未來修訂版本中變更，我們不保證能前瞻或回溯相容。

  • 可信任

    boolean

    信任驗證的結果：如果可信任特定驗證詳細資料，則為 true；如果信任基於任何原因而遭拒，則為 false。

方法

getKeyPair()

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

將用於搭配使用的 certificate 金鑰組platformKeys.subtleCrypto傳送到 callback。

參數

  • 認證

    ArrayBuffer

    selectClientCertificates 傳回的 Match 憑證。

  • 參數

    物件

    除了決定金鑰本身固定的參數外，還要決定簽章/雜湊演算法參數。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

      物件選用

      如果這項擴充功能無法存取，可能為 null。

getKeyPairBySpki()

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

將 publicKeySpkiDer 識別的金鑰組傳送至 callback，以便與 platformKeys.subtleCrypto 搭配使用。

參數

  • publicKeySpkiDer

    ArrayBuffer

    採用 DER 編碼的 X.509 SubjectPublicKeyInfo，例如透過以下格式呼叫 WebCrypto 的 exportKey 函數而得。

  • 參數

    物件

    提供簽章和雜湊演算法參數，以及金鑰本身修正的參數。WebCrypto 的 importKey 函式接受相同的參數，例如 RsaHashedImportParams 代表 RSASSA-PKCS1-v1_5 金鑰。如果是 RSASSA-PKCS1-v1_5 金鑰，還需要傳遞「hash」參數 { "hash": { "name": string } }。「hash」參數代表在符號前要用於摘要作業的雜湊演算法名稱。您可以傳遞「none」做為雜湊名稱，在此情況下，簽署函式會套用 PKCS#1 v1.5 邊框間距，但不會對指定資料進行雜湊處理。

    目前這個方法支援採用「none」、「SHA-1」、「SHA-256」、「SHA-384」和「SHA-512」其中一種雜湊演算法的「ECDSA」演算法。

  • 回呼

    功能

    callback 參數如下所示： 

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

    • publicKey

      物件

    • privateKey

      物件選用

      如果這項擴充功能無法存取，可能為 null。

selectClientCertificates()

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

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

參數

  • 詳細資料

    SelectDetails

  • 回呼

    函式選用

    callback 參數如下所示： 

    (matches: Match[])=>void

    • 相符項目

      相符[]

      符合要求的憑證清單，擴充功能具有權限，如果 interactive 為 true，則由使用者選取的憑證清單。

傳回

  • Promise<Match[]>

    Chrome 121 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

subtleCrypto()

chrome.platformKeys.subtleCrypto()

實作 WebCrypto 的 SubtleCrypto，允許這個擴充功能可用的用戶端憑證金鑰進行密碼編譯。

傳回

  • 物件|未定義

verifyTLSServerCertificate()

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

檢查根據平台的信任設定，檢查 details.hostname 是否可信任 details.serverCertificateChain。注意：信任驗證的實際行為並未完整說明，日後可能會改變。API 實作項目會驗證憑證到期日、驗證憑證路徑，並檢查已知 CA 的信任情況。實作應遵循 EKU ServerAuth ，並支援主體別名。

參數

傳回

  • Chrome 121 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。