chrome.certificateProvider

説明

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

権限

certificateProvider

対象

Chrome 46 以降 ChromeOS のみ をご覧ください。

用途

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

  • 拡張機能は、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

    ハッシュ[]

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

CertificatesUpdateRequest

Chrome 86 以降

プロパティ

  • certificatesRequestId

    数値

    setCertificates に渡すリクエスト ID。

ClientCertificateInfo

Chrome 86 以降

プロパティ

  • certificateChain

    ArrayBuffer[]

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

    証明書に含める証明書は 1 つだけです。

  • supportedAlgorithms

    アルゴリズム[]

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

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

    数値（省略可）

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

  • errorType

    PinRequestErrorType optional

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

  • requestType

    PinRequestType（省略可）

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

  • signRequestId

    数値

    Chrome が SignRequest で指定した ID。

SetCertificatesDetails

Chrome 86 以降

プロパティ

  • certificatesRequestId

    数値（省略可）

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

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

StopPinRequestDetails

Chrome 57 以降

プロパティ

  • errorType

    PinRequestErrorType optional

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

  • signRequestId

    数値

    Chrome が SignRequest で指定した ID。

メソッド

reportSignature()

<ph type="x-smartling-placeholder"></ph> 約束 Chrome 86 以降 をご覧ください。
chrome.certificateProvider.reportSignature(
  details: ReportSignatureDetails,
  callback?: function,
)

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

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

パラメータ

  • callback

    関数（省略可）

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

    () => void

戻り値

  • 約束 <void>

    Chrome 96 以降

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

requestPin()

<ph type="x-smartling-placeholder"></ph> 約束 Chrome 57 以降 をご覧ください。
chrome.certificateProvider.requestPin(
  details: RequestPinDetails,
  callback?: function,
)

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

パラメータ

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

  • callback

    関数（省略可）

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

    (details?: PinResponseDetails) => void

戻り値

  • Promise&lt;PinResponseDetails |未定義>

    Chrome 96 以降

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

setCertificates()

<ph type="x-smartling-placeholder"></ph> 約束 Chrome 86 以降 をご覧ください。
chrome.certificateProvider.setCertificates(
  details: SetCertificatesDetails,
  callback?: function,
)

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

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

パラメータ

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

  • callback

    関数（省略可）

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

    () => void

戻り値

  • 約束 <void>

    Chrome 96 以降

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

stopPinRequest()

<ph type="x-smartling-placeholder"></ph> 約束 Chrome 57 以降 をご覧ください。
chrome.certificateProvider.stopPinRequest(
  details: StopPinRequestDetails,
  callback?: function,
)

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

パラメータ

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

  • callback

    関数（省略可）

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

    () => void

戻り値

  • 約束 <void>

    Chrome 96 以降

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

イベント

onCertificatesRequested

Chrome 47 以降 &amp;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

<ph type="x-smartling-placeholder"></ph> &amp;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（省略可）