説明
この API を使用して、TLS 認証にこれらの証明書を使用できるプラットフォームに証明書を公開します。
権限
certificateProvider
可用性
コンセプトと使用方法
この 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
サポートされている暗号署名アルゴリズムのタイプ。
列挙型
"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
プロパティ
-
certificatesRequestId
数値
setCertificates
に渡されるリクエスト ID。
ClientCertificateInfo
プロパティ
-
certificateChain
ArrayBuffer[]
配列には、最初の要素として X.509 クライアント証明書の DER エンコードを含める必要があります。
証明書は 1 つのみ含める必要があります。
-
supportedAlgorithms
アルゴリズム[]
この証明書でサポートされているすべてのアルゴリズム。拡張機能は、これらのアルゴリズムのいずれかを使用した署名のみを要求します。
Error
拡張機能が報告できるエラーのタイプ。
値
Hash
非推奨です。Algorithm
に置き換えられました。
列挙型
"MD5_SHA1"
MD5 および SHA1 ハッシュ アルゴリズムを指定します。
"SHA1"
SHA1 ハッシュ アルゴリズムを指定します。
"SHA256"
SHA256 ハッシュ アルゴリズムを指定します。
"SHA384"
SHA384 ハッシュ アルゴリズムを指定します。
"SHA512"
SHA512 ハッシュ アルゴリズムを指定します。
PinRequestErrorType
requestPin 関数を使用してユーザーに表示されるエラーの種類です。
列挙型
"INVALID_PIN"
PIN が無効であることを示します。
"INVALID_PUK"
PUK が無効であることを指定します。
"MAX_ATTEMPTS_EXCEEDED"
最大試行回数を超えたことを示します。
"UNKNOWN_ERROR"
エラーを上記のタイプで表すことができないことを指定します。
PinRequestType
requestPin 関数を使用して拡張機能からリクエストされるコードのタイプ。
列挙型
"PIN"
リクエストされたコードが PIN であることを指定します。
"PUK"
リクエストされたコードが PUK であることを指定します。
PinResponseDetails
プロパティ
-
userInput
string(省略可)
ユーザーが指定したコード。ユーザーがダイアログを閉じた場合や他のエラーが発生した場合は空になります。
ReportSignatureDetails
プロパティ
-
error
省略可
署名の生成中に発生したエラー(ある場合)。
-
signRequestId
数値
onSignatureRequested
イベントを介して受信したリクエスト ID。 -
signature
ArrayBuffer 省略可
署名(正常に生成された場合)。
RequestPinDetails
プロパティ
-
attemptsLeft
number(省略可)
残りの試行回数。これは、どの UI でもこの情報をユーザーに表示できるようにするために設けられています。Chrome ではこれを適用することは想定されていません。代わりに、固定リクエストの数を超えたときに、拡張機能で errorType = MAX_ATTEMPTS_EXCEEDED で stopPinRequest を呼び出す必要があります。
-
errorType
ユーザーに表示されるエラー テンプレート。前のリクエストが失敗した場合に、失敗した理由をユーザーに通知するために設定します。
-
requestType
PinRequestType 省略可
リクエストされたコードの種類。デフォルトは PIN です。
-
signRequestId
数値
Chrome の SignRequest で指定された ID。
SetCertificatesDetails
プロパティ
-
certificatesRequestId
number(省略可)
onCertificatesUpdateRequested
へのレスポンスとして呼び出される場合は、受信したcertificatesRequestId
値が含まれている必要があります。それ以外の場合は、未設定のままにする必要があります。 -
clientCertificates
現在利用可能なクライアント証明書のリスト。
-
error
省略可
証明書の抽出中に発生したエラー(ある場合)。このエラーは、必要に応じてユーザーに表示されます。
SignatureRequest
プロパティ
-
algorithm
使用する署名アルゴリズム。
-
認定書
ArrayBuffer
X.509 証明書の DER エンコード。拡張機能は、関連付けられた秘密鍵を使用して
input
に署名する必要があります。 -
入力
ArrayBuffer
署名するデータ。データはハッシュ化されません。
-
signRequestId
数値
reportSignature
に渡されるリクエスト ID。
SignRequest
プロパティ
-
認定書
ArrayBuffer
X.509 証明書の DER エンコード。拡張機能は、関連付けられた秘密鍵を使用して
digest
に署名する必要があります。 -
ダイジェスト
ArrayBuffer
署名が必要なダイジェスト。
-
ハッシュ
digest
の作成に使用されたハッシュ アルゴリズムを指します。 -
signRequestId
数値
Chrome 57 以降必要なメソッド(requestPin など)を呼び出す必要がある場合に、拡張機能が使用する一意の ID。
StopPinRequestDetails
プロパティ
-
errorType
エラー テンプレート。存在する場合は、ユーザーに表示されます。MAX_ATTEMPTS_EXCEEDED など、エラーが原因でフローを停止する理由が含まれます。
-
signRequestId
数値
Chrome の SignRequest で指定された ID。
メソッド
reportSignature()
chrome.certificateProvider.reportSignature(
details: ReportSignatureDetails,
callback?: function,
)
onSignatureRequested
へのレスポンスとして呼び出す必要があります。
拡張機能は最終的に、onSignatureRequested
イベントごとにこの関数を呼び出す必要があります。API 実装はしばらくするとこの呼び出しの待機を停止し、この関数が呼び出されるとタイムアウト エラーで応答します。
パラメータ
-
callback
関数(省略可)
callback
パラメータは次のようになります。() => void
戻り値
-
Promise<void>
Chrome 96 以降Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。
requestPin()
chrome.certificateProvider.requestPin(
details: RequestPinDetails,
callback?: function,
)
ユーザーに PIN をリクエストします。一度に処理できるリクエストは 1 つのみです。別のフローの進行中に発行されたリクエストは拒否されます。別のフローが進行中の場合は、拡張機能が後で再試行する必要があります。
パラメータ
-
リクエストされたダイアログに関する詳細が含まれます。
-
callback
関数(省略可)
callback
パラメータは次のようになります。(details?: PinResponseDetails) => void
-
詳細
-
戻り値
-
Promise<PinResponseDetails | undefined>
Chrome 96 以降Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。
setCertificates()
chrome.certificateProvider.setCertificates(
details: SetCertificatesDetails,
callback?: function,
)
ブラウザで使用する証明書のリストを設定します。
この拡張機能は、初期化後と、現在利用可能な証明書セットが変更されるたびに、この関数を呼び出す必要があります。また、拡張機能は、このイベントを受信するたびに onCertificatesUpdateRequested
に応じてこの関数を呼び出す必要もあります。
パラメータ
-
設定する証明書。無効な証明書は無視されます。
-
callback
関数(省略可)
callback
パラメータは次のようになります。() => void
戻り値
-
Promise<void>
Chrome 96 以降Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。
stopPinRequest()
chrome.certificateProvider.stopPinRequest(
details: StopPinRequestDetails,
callback?: function,
)
requestPin
関数によって開始された固定リクエストを停止します。
パラメータ
-
リクエスト フローを停止する理由の詳細が含まれます。
-
callback
関数(省略可)
callback
パラメータは次のようになります。() => void
戻り値
-
Promise<void>
Chrome 96 以降Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。
イベント
onCertificatesRequested
chrome.certificateProvider.onCertificatesRequested.addListener(
callback: function,
)
代わりに onCertificatesUpdateRequested
を使用してください。
このイベントは、この拡張機能によって提供される現在の証明書のリストをブラウザがリクエストするたびに発生します。拡張機能は、現在の証明書リストを使用して reportCallback
を 1 回だけ呼び出す必要があります。
パラメータ
-
callback
機能
callback
パラメータは次のようになります。(reportCallback: function) => void
-
reportCallback
機能
reportCallback
パラメータは次のようになります。(certificates: CertificateInfo[], callback: function) => void
-
certificates
-
callback
機能
callback
パラメータは次のようになります。(rejectedCertificates: ArrayBuffer[]) => void
-
rejectedCertificates
ArrayBuffer[]
-
-
-
onCertificatesUpdateRequested
chrome.certificateProvider.onCertificatesUpdateRequested.addListener(
callback: function,
)
このイベントは、setCertificates
で設定された証明書が不十分な場合、またはブラウザが更新された情報を要求した場合に発生します。拡張機能は、更新された証明書のリストと受信した certificatesRequestId
を使用して setCertificates
を呼び出す必要があります。
パラメータ
-
callback
機能
callback
パラメータは次のようになります。(request: CertificatesUpdateRequest) => void
-
request
-
onSignatureRequested
chrome.certificateProvider.onSignatureRequested.addListener(
callback: function,
)
このイベントは、この拡張機能から setCertificates
を介して提供される証明書を使用して、ブラウザがメッセージに署名する必要があるたびに発生します。
この拡張機能は、適切なアルゴリズムと秘密鍵を使用して request
からの入力データに署名し、受け取った signRequestId
で reportSignature
を呼び出すことでそれを返す必要があります。
パラメータ
-
callback
機能
callback
パラメータは次のようになります。(request: SignatureRequest) => void
-
request
-
onSignDigestRequested
chrome.certificateProvider.onSignDigestRequested.addListener(
callback: function,
)
代わりに onSignatureRequested
を使用してください。
このイベントは、onCertificatesRequested
イベントへの応答として、この拡張機能が提供する証明書を使用してブラウザがメッセージに署名する必要があるたびに発生します。この拡張機能は、適切なアルゴリズムと秘密鍵を使用して request
内のデータに署名し、reportCallback
を呼び出してそれを返す必要があります。reportCallback
は 1 回だけ呼び出す必要があります。
パラメータ
-
callback
機能
callback
パラメータは次のようになります。(request: SignRequest, reportCallback: function) => void
-
request
-
reportCallback
機能
Chrome 47 以降reportCallback
パラメータは次のようになります。(signature?: ArrayBuffer) => void
-
signature
ArrayBuffer 省略可
-
-