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 會在此清單中運作。如果不是，則從平台的憑證存放區取得可用於這個擴充功能的所有憑證清單。系統會移除擴充功能不具備權限或不符合要求的項目。

  • 互動

    布林值

    如果設為 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。

參數

  • 詳細資料

    SelectDetails

  • 回呼

    函式 選用

    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 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。