chrome.certificateProvider

説明

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

権限

certificateProvider

対象

Chrome 46 以降 ChromeOS のみ

コンセプトと使用方法

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

  • 拡張機能は、イベント onCertificatesUpdateRequested と onSignatureRequested を登録します。
  • Extension は 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

    number（省略可）

    残りの試行回数。これは、任意の UI がこの情報をユーザーに表示できるように提供されています。Chrome はこれを適用しません。代わりに、ピン リクエストの数が超過した場合は、拡張機能によって stopPinRequest が errorType = MAX_ATTEMPTS_EXCEEDED で呼び出されます。

  • 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,
)

onSignatureRequested へのレスポンスとして呼び出されます。

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

パラメータ

  • callback

    function 省略可

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

    () => void

戻り値

  • Promise<void>

    Chrome 96 以降

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

requestPin()

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

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

パラメータ

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

  • callback

    function 省略可

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

    (details?: PinResponseDetails) => void

戻り値

  • Promise<PinResponseDetails | undefined>

    Chrome 96 以降

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

setCertificates()

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

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

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

パラメータ

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

  • callback

    function 省略可

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

    () => void

戻り値

  • Promise<void>

    Chrome 96 以降

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

stopPinRequest()

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

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

パラメータ

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

  • callback

    function 省略可

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

    () => void

戻り値

  • Promise<void>

    Chrome 96 以降

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

イベント

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 を呼び出して返す必要があります。

パラメータ