chrome.certificateProvider

説明

この API を使用して証明書をプラットフォームに公開すると、そのプラットフォームはこの証明書を TLS 認証に使用できます。

権限

certificateProvider

対象

Chrome 46 以降 ChromeOS のみ

用途

この API を使用してクライアント証明書を ChromeOS に公開する一般的な手順は次のとおりです。

  • 拡張機能は、イベント onCertificatesUpdateRequested と onSignatureRequested に登録します。
  • 拡張機能は、初期化後に setCertificates を呼び出して証明書の初期リストを提供します。
  • 拡張機能は、利用可能な証明書のリストの変更をモニタリングし、setCertificates を呼び出して、そのような変更をブラウザに通知します。
  • TLS handshake 中に、ブラウザはクライアント証明書リクエストを受け取ります。onCertificatesUpdateRequested イベントにより、ブラウザは拡張機能に対し、現在提供しているすべての証明書を報告するよう求めます。
  • 拡張機能は、setCertificates メソッドを使用して、現在利用可能な証明書をレポートで返します。
  • ブラウザは、利用可能なすべての証明書をリモートホストからのクライアント証明書リクエストと照合します。一致する候補が選択ダイアログに表示されます。
  • ユーザーは証明書を選択して認証を承認するか、認証を中止できます。

証明書選択ダイアログ

  • ユーザーが認証を中止した場合、またはリクエストに一致する証明書がない場合、TLS クライアント認証は中止されます。
  • それ以外の場合、ユーザーがこの拡張機能から提供された証明書で認証を承認すると、ブラウザは拡張機能にデータの署名をリクエストして、TLS handshake を続行します。リクエストは onSignatureRequested イベントとして送信されます。
  • このイベントには入力データが含まれ、署名の生成に使用するアルゴリズムが宣言され、この拡張機能によって報告された証明書のいずれかが参照されます。拡張機能は、参照された証明書に関連付けられた秘密鍵を使用して、指定されたデータの署名を作成する必要があります。署名を作成するには、DigestInfo を先頭に追加し、実際の署名の前に結果をパディングする必要がある場合があります。
  • 拡張機能は、reportSignature メソッドを使用して署名をブラウザに返します。署名を計算できなかった場合は、署名なしでメソッドを呼び出す必要があります。
  • 署名が提供された場合、ブラウザは TLS handshake を完了します。

実際の手順は異なる場合があります。たとえば、証明書を自動的に選択するエンタープライズ ポリシーが使用されている場合、ユーザーに証明書の選択を求めることはありません（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 パディングのみを追加する必要があります。このアルゴリズムは非推奨であり、バージョン 109 以降の Chrome でリクエストされることはありません。

"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

    Hash[]

    この証明書でサポートされているすべてのハッシュに設定する必要があります。この拡張機能は、これらのハッシュ アルゴリズムのいずれかで計算されたダイジェストの署名のみを求めます。これは、ハッシュの優先度の高い順に並べる必要があります。

CertificatesUpdateRequest

Chrome 86 以降

プロパティ

  • certificatesRequestId

    数値

    setCertificates に渡されるリクエスト ID。

ClientCertificateInfo

Chrome 86 以降

プロパティ

  • certificateChain

    ArrayBuffer[]

    配列の最初の要素として、X.509 クライアント証明書の DER エンコードを含める必要があります。

    これには証明書が 1 つだけ含まれている必要があります。

  • supportedAlgorithms

    Algorithm[]

    この証明書でサポートされているすべてのアルゴリズム。拡張機能に署名が求められるのは、これらのアルゴリズムのいずれかを使用する場合のみです。

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

    文字列 省略可

    ユーザーが指定したコード。ユーザーがダイアログを閉じた場合や、その他のエラーが発生した場合は空になります。

ReportSignatureDetails

Chrome 86 以降

プロパティ

  • エラー

    "GENERAL_ERROR"
     省略可

    署名の生成中に発生したエラー（存在する場合）。

  • signRequestId

    数値

    onSignatureRequested イベントで受信したリクエスト ID。

  • signature

    ArrayBuffer 省略可

    署名（正常に生成された場合）。

RequestPinDetails

Chrome 57+

プロパティ

  • attemptsLeft

    number 省略可

    残りの試行回数。これは、あらゆる UI がこの情報をユーザーに提示できるようにするために提供されます。Chrome はこれを強制しません。代わりに、PIN リクエストの数が上限を超えた場合は、拡張機能から errorType = MAX_ATTEMPTS_EXCEEDED を指定して stopPinRequest を呼び出す必要があります。

  • errorType

    PinRequestErrorType 省略可

    ユーザーに表示されるエラー テンプレート。前のリクエストが失敗した場合に、失敗理由をユーザーに通知するために設定します。

  • requestType

    PinRequestType 省略可

    リクエストされたコードのタイプ。デフォルトは PIN です。

  • signRequestId

    数値

    SignRequest で Chrome から付与された ID。

SetCertificatesDetails

Chrome 86 以降

プロパティ

  • certificatesRequestId

    number 省略可

    onCertificatesUpdateRequested への応答で呼び出された場合、受信した certificatesRequestId 値が含まれます。それ以外の場合は設定を解除する必要があります。

  • clientCertificates

    ClientCertificateInfo[]

    現在利用可能なクライアント証明書のリスト。

  • エラー

    "GENERAL_ERROR"
     省略可

    証明書の抽出中に発生したエラー（存在する場合）。このエラーは、必要に応じてユーザーに表示されます。

SignatureRequest

Chrome 86 以降

プロパティ

  • algorithm

    Algorithm

    使用する署名アルゴリズム。

  • 証明書

    ArrayBuffer

    X.509 証明書の DER エンコード。拡張機能は、関連付けられた秘密鍵を使用して input に署名する必要があります。

  • 入力

    ArrayBuffer

    署名するデータ。データはハッシュ化されません。

  • signRequestId

    数値

    reportSignature に渡されるリクエスト ID。

SignRequest

プロパティ

  • 証明書

    ArrayBuffer

    X.509 証明書の DER エンコード。拡張機能は、関連付けられた秘密鍵を使用して digest に署名する必要があります。

  • ダイジェスト

    ArrayBuffer

    署名が必要なダイジェスト。

  • ハッシュ

    ハッシュ

    digest の作成に使用されたハッシュ アルゴリズムを指します。

  • signRequestId

    数値

    Chrome 57+

    拡張機能が requestPin などの ID を必要とするメソッドを呼び出す必要がある場合に使用される一意の ID。

StopPinRequestDetails

Chrome 57+

プロパティ

  • errorType

    PinRequestErrorType 省略可

    エラー テンプレート。存在する場合はユーザーに表示されます。エラーが原因でフローが停止した場合に、停止理由（MAX_ATTEMPTS_EXCEEDED など）を含めることを目的としています。

  • signRequestId

    数値

    SignRequest で Chrome から付与された ID。

メソッド

reportSignature()

Promise Chrome 86 以降 
chrome.certificateProvider.reportSignature(
  details: ReportSignatureDetails,
  callback?: function,
): Promise<void>

onSignatureRequested のレスポンスとして呼び出される必要があります。

拡張機能は、すべての onSignatureRequested イベントに対して最終的にこの関数を呼び出す必要があります。API 実装は、この呼び出しをしばらく待ってから、この関数が呼び出されたときにタイムアウト エラーで応答します。

パラメータ

  • callback

    関数 省略可

    callback パラメータは次のようになります。 

    () => void

戻り値

  • Promise<void>

    Chrome 96 以降

    Promise は Manifest V3 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。

requestPin()

Promise Chrome 57 以降 
chrome.certificateProvider.requestPin(
  details: RequestPinDetails,
  callback?: function,
): Promise<PinResponseDetails | undefined>

ユーザーに PIN をリクエストします。一度に進行中のリクエストは 1 つのみです。別のフローが進行中に発行されたリクエストは拒否されます。別のフローが進行中の場合は、後で再試行するのは拡張機能の責任です。

パラメータ

戻り値

  • Promise<PinResponseDetails | undefined>

    Chrome 96 以降

    Promise は Manifest V3 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。

setCertificates()

Promise Chrome 86 以降 
chrome.certificateProvider.setCertificates(
  details: SetCertificatesDetails,
  callback?: function,
): Promise<void>

ブラウザで使用する証明書のリストを設定します。

拡張機能は、初期化後、および現在利用可能な証明書のセットが変更されるたびに、この関数を呼び出す必要があります。拡張機能は、このイベントが受信されるたびに onCertificatesUpdateRequested に応答してこの関数も呼び出す必要があります。

パラメータ

  • 設定する証明書。無効な証明書は無視されます。

  • callback

    関数 省略可

    callback パラメータは次のようになります。 

    () => void

戻り値

  • Promise<void>

    Chrome 96 以降

    Promise は Manifest V3 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。

stopPinRequest()

Promise Chrome 57 以降 
chrome.certificateProvider.stopPinRequest(
  details: StopPinRequestDetails,
  callback?: function,
): Promise<void>

requestPin 関数によって開始された PIN リクエストを停止します。

パラメータ

  • リクエスト フローを停止した理由の詳細が含まれます。

  • callback

    関数 省略可

    callback パラメータは次のようになります。 

    () => void

戻り値

  • Promise<void>

    Chrome 96 以降

    Promise は Manifest V3 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。

イベント

onCertificatesRequested

Chrome 47 以降 &leq; MV2 Chrome 86 以降で非推奨
chrome.certificateProvider.onCertificatesRequested.addListener(
  callback: function,
)

代わりに onCertificatesUpdateRequested を使用してください。

このイベントは、ブラウザがこの拡張機能によって提供される証明書の現在のリストをリクエストするたびに発生します。拡張機能は、現在の証明書のリストを使用して reportCallback を 1 回だけ呼び出す必要があります。

パラメータ

  • callback

    関数

    callback パラメータは次のようになります。 

    (reportCallback: function) => void

    • reportCallback

      関数

      reportCallback パラメータは次のようになります。 

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

      • 証明書

        CertificateInfo[]

      • callback

        関数

        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 からの入力データに署名し、受け取った signRequestId を使用して reportSignature を呼び出すことで返さなければなりません。

パラメータ

onSignDigestRequested

&leq; MV2 Chrome 86 以降で非推奨
chrome.certificateProvider.onSignDigestRequested.addListener(
  callback: function,
)

代わりに onSignatureRequested を使用してください。

このイベントは、ブラウザが onCertificatesRequested イベントへの応答としてこの拡張機能が提供する証明書を使用してメッセージに署名する必要があるたびに発生します。拡張機能は、適切なアルゴリズムと秘密鍵を使用して request のデータに署名し、reportCallback を呼び出して返さなければなりません。reportCallback は 1 回だけ呼び出す必要があります。

パラメータ

  • callback

    関数

    callback パラメータは次のようになります。 

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

    • リクエスト

      SignRequest

    • reportCallback

      関数

      Chrome 47 以降

      reportCallback パラメータは次のようになります。 

      (signature?: ArrayBuffer) => void

      • signature

        ArrayBuffer 省略可