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 以降

サポートされている暗号署名アルゴリズムのタイプ。

Enum

"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"
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

    ハッシュ[]

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

CertificatesUpdateRequest

Chrome 86 以降

プロパティ

  • certificatesRequestId

    数値

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

ClientCertificateInfo

Chrome 86 以降

プロパティ

  • certificateChain

    ArrayBuffer[]

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

    証明書は 1 つのみ含める必要があります。

  • supportedAlgorithms

    アルゴリズム[]

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

Error

Chrome 86 以降

拡張機能が報告できるエラーのタイプ。

値

Hash

非推奨です。Algorithm に置き換えられました。

Enum

"MD5_SHA1"
MD5 および SHA1 ハッシュ アルゴリズムを指定します。

"SHA1"
SHA1 ハッシュ アルゴリズムを指定します。

"SHA256"
SHA256 ハッシュ アルゴリズムを指定します。

"SHA384"
SHA384 ハッシュ アルゴリズムを指定します。

"SHA512"
SHA512 ハッシュ アルゴリズムを指定します。

PinRequestErrorType

Chrome 57 以降

requestPin 関数を使用してユーザーに表示されるエラーの種類です。

Enum

"INVALID_PIN"
PIN が無効であることを示します。

"INVALID_PUK"
PUK が無効であることを指定します。

"MAX_ATTEMPTS_EXCEEDED"
最大試行回数を超えたことを示します。

"UNKNOWN_ERROR"
エラーを上記のタイプで表すことができないことを指定します。

PinRequestType

Chrome 57 以降

requestPin 関数を使用して拡張機能からリクエストされるコードのタイプ。

Enum

"PIN"
リクエストされたコードが PIN であることを指定します。

"PUK"
リクエストされたコードが PUK であることを指定します。

PinResponseDetails

Chrome 57 以降

プロパティ

  • userInput

    string（省略可）

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

ReportSignatureDetails

Chrome 86 以降

プロパティ

  • error

     省略可

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

  • signRequestId

    数値

    onSignatureRequested イベントを介して受信したリクエスト ID。

  • signature

    ArrayBuffer 省略可

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

RequestPinDetails

Chrome 57 以降

プロパティ

  • attemptsLeft

    number（省略可）

    残りの試行回数。これは、どの UI でもこの情報をユーザーに表示できるようにするために設けられています。Chrome ではこれを適用することは想定されていません。代わりに、固定リクエストの数を超えたときに、拡張機能で errorType = MAX_ATTEMPTS_EXCEEDED で stopPinRequest を呼び出す必要があります。

  • errorType

    PinRequestErrorType 省略可

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

  • requestType

    PinRequestType 省略可

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

  • signRequestId

    数値

    Chrome の SignRequest で指定された ID。

SetCertificatesDetails

Chrome 86 以降

プロパティ

  • certificatesRequestId

    number（省略可）

    onCertificatesUpdateRequested へのレスポンスとして呼び出される場合は、受信した certificatesRequestId 値が含まれている必要があります。それ以外の場合は、未設定のままにする必要があります。

  • clientCertificates

    ClientCertificateInfo[]

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

  • 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。

StopPinRequestDetails

Chrome 57 以降

プロパティ

  • errorType

    PinRequestErrorType 省略可

    エラー テンプレート。存在する場合は、ユーザーに表示されます。MAX_ATTEMPTS_EXCEEDED など、エラーが原因でフローを停止する理由が含まれます。

  • signRequestId

    数値

    Chrome の SignRequest で指定された ID。

Methods

reportSignature()

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

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

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

パラメータ

  • callback

    関数（省略可）

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

    ()=>void

戻り値

  • Promise<void>

    Chrome 96 以降

    Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。

requestPin()

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

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

パラメータ

  • リクエストされたダイアログに関する詳細が含まれます。

  • callback

    関数（省略可）

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

    (details?: PinResponseDetails)=>void

戻り値

  • Promise<PinResponseDetailsPinResponseDetails|未定義>

    Chrome 96 以降

    Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。

setCertificates()

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

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

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

パラメータ

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

  • callback

    関数（省略可）

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

    ()=>void

戻り値

  • Promise<void>

    Chrome 96 以降

    Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。

stopPinRequest()

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

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

パラメータ

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

  • callback

    関数（省略可）

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

    ()=>void

戻り値

  • Promise<void>

    Chrome 96 以降

    Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。

イベント

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

      • certificates

        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

    • request

      SignRequest

    • reportCallback

      機能

      Chrome 47 以降

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

      (signature?: ArrayBuffer)=>void

      • signature

        ArrayBuffer 省略可