説明
この API を使用して、TLS 認証に使用できる証明書をプラットフォームに公開します。
権限
certificateProvider対象
コンセプトと使用方法
この API を使用してクライアント証明書を ChromeOS に公開する一般的な手順は次のとおりです。
- 拡張機能は、イベント
onCertificatesUpdateRequestedとonSignatureRequestedに登録します。 - 拡張機能は、初期化後に
setCertificates()を呼び出して、証明書の初期リストを提供します。 - 拡張機能は、利用可能な証明書のリストの変更をモニタリングし、
setCertificates()を呼び出して、そのような変更をブラウザに通知します。 - TLS handshake 中に、ブラウザはクライアント証明書リクエストを受信します。
onCertificatesUpdateRequestedイベントが発生すると、ブラウザは拡張機能に対し、現在提供しているすべての証明書を報告するよう要求します。 - 拡張機能は、
setCertificates()メソッドを使用して、現在利用可能な証明書を報告します。 - ブラウザは、利用可能なすべての証明書をリモートホストからのクライアント証明書リクエストと照合します。一致するものが選択ダイアログでユーザーに表示されます。
- ユーザーは証明書を選択して、認証を承認または中止できます。
- ユーザーが認証を中止した場合、またはリクエストに一致する証明書がない場合、TLS クライアント認証は中止されます。
- ユーザーがこの拡張機能によって提供された証明書を使用した認証を承認すると、ブラウザは拡張機能にデータの署名をリクエストして TLS handshake を続行します。リクエストは
onSignatureRequestedイベントとして送信されます。 - このイベントには、入力データが含まれ、署名の生成に使用する必要があるアルゴリズムが宣言され、この拡張機能によって報告された証明書の 1 つが参照されます。拡張機能は、参照された証明書に関連付けられた秘密鍵を使用して、指定されたデータの署名を作成する必要があります。署名を作成するには、実際の署名の前に 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() {
browser.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.
browser.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.
browser.certificateProvider.reportSignature({
signRequestId: request.signRequestId,
error: 'GENERAL_ERROR'
});
return;
}
const signature = signUnhashedData(key, request.input, request.algorithm);
browser.certificateProvider.reportSignature({
signRequestId: request.signRequestId,
signature: signature
});
}
browser.certificateProvider.onCertificatesUpdateRequested.addListener(
handleCertificatesUpdateRequest);
browser.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
拡張機能が報告できるエラーの種類。
値
"GENERAL_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
文字列 省略可
ユーザーが指定したコード。ユーザーがダイアログを閉じた場合や、その他のエラーが発生した場合は空になります。
ReportSignatureDetails
プロパティ
-
エラー
"GENERAL_ERROR"
省略可署名の生成中に発生したエラー（存在する場合）。
-
signRequestId
数値
onSignatureRequestedイベントを介して受信したリクエスト ID。 -
signature
ArrayBuffer 省略可
正常に生成された場合は、署名。
RequestPinDetails
プロパティ
-
attemptsLeft
number 省略可
残りの試行回数。これは、UI がこの情報をユーザーに提示できるようにするために提供されます。Chrome はこれを適用するのではなく、PIN リクエストの数が上限を超えたときに、errorType = MAX_ATTEMPTS_EXCEEDED で拡張機能から stopPinRequest を呼び出す必要があります。
-
errorType
ユーザーに表示されるエラー テンプレート。これは、以前のリクエストが失敗した場合に、失敗の理由をユーザーに通知するために設定する必要があります。
-
requestType
PinRequestType 省略可
リクエストされたコードのタイプ。デフォルトは PIN です。
-
signRequestId
数値
SignRequest で Chrome によって指定された ID。
SetCertificatesDetails
プロパティ
-
certificatesRequestId
number 省略可
onCertificatesUpdateRequestedに応答して呼び出された場合、受信したcertificatesRequestId値が含まれている必要があります。それ以外の場合は、設定しないでください。 -
clientCertificates
現在利用可能なクライアント証明書のリスト。
-
エラー
"GENERAL_ERROR"
省略可証明書の抽出中に発生したエラー（エラーが存在する場合）。このエラーは、必要に応じてユーザーに表示されます。
SignatureRequest
プロパティ
-
algorithm
使用する署名アルゴリズム。
-
証明書
ArrayBuffer
X.509 証明書の DER エンコード。拡張機能は、関連付けられた秘密鍵を使用して
inputに署名する必要があります。 -
入力
ArrayBuffer
署名するデータ。データはハッシュ化されません。
-
signRequestId
数値
reportSignatureに渡されるリクエスト ID。
SignRequest
プロパティ
-
証明書
ArrayBuffer
X.509 証明書の DER エンコード。拡張機能は、関連付けられた秘密鍵を使用して
digestに署名する必要があります。 -
ダイジェスト
ArrayBuffer
署名する必要があるダイジェスト。
-
ハッシュ
digestの作成に使用されたハッシュ アルゴリズムを指します。 -
signRequestId
数値
Chrome 57 以降 Chrome 148 以降の browser.*一意の ID を必要とするメソッド（requestPin など）を呼び出す必要がある場合に、拡張機能で使用される一意の ID。
StopPinRequestDetails
プロパティ
-
errorType
エラー テンプレート。存在する場合は、ユーザーに表示されます。エラー（MAX_ATTEMPTS_EXCEEDED など）が原因でフローが停止した場合に、その理由を格納することを目的としています。
-
signRequestId
数値
SignRequest で Chrome によって指定された ID。
メソッド
reportSignature()
browser.certificateProvider.reportSignature(
details: ReportSignatureDetails,
): Promise<void>
onSignatureRequested へのレスポンスとして呼び出す必要があります。
拡張機能は、最終的にすべての onSignatureRequested イベントに対してこの関数を呼び出す必要があります。API 実装は、しばらくするとこの呼び出しの待機を停止し、この関数が呼び出されるとタイムアウト エラーを返します。
パラメータ
戻り値
-
Promise<void>
Chrome 96 以降 Chrome 148 以降の browser.*
requestPin()
browser.certificateProvider.requestPin(
details: RequestPinDetails,
): Promise<PinResponseDetails | undefined>
ユーザーに PIN をリクエストします。一度に実行できるリクエストは 1 つだけです。別のフローの進行中に発行されたリクエストは拒否されます。別のフローが進行中の場合は、しばらくしてからもう一度試すのが拡張機能の役割です。
パラメータ
-
リクエストされたダイアログの詳細が含まれます。
戻り値
-
Promise<PinResponseDetails | undefined>
Chrome 96 以降 Chrome 148 以降の browser.*ユーザーが PIN を入力すると解決される Promise を返します。ダイアログ リクエストが正常に完了しなかった場合（ユーザーがダイアログをキャンセルした、ダイアログの表示が許可されなかったなど）、エラーで拒否されます。
setCertificates()
browser.certificateProvider.setCertificates(
details: SetCertificatesDetails,
): Promise<void>
ブラウザで使用する証明書のリストを設定します。
拡張機能は、初期化後、および現在利用可能な証明書のセットが変更されるたびに、この関数を呼び出す必要があります。また、拡張機能は、onCertificatesUpdateRequested イベントを受信するたびに、この関数を呼び出す必要があります。
パラメータ
-
設定する証明書。無効な証明書は無視されます。
戻り値
-
Promise<void>
Chrome 96 以降 Chrome 148 以降の browser.*完了時に解決される Promise を返します。
stopPinRequest()
browser.certificateProvider.stopPinRequest(
details: StopPinRequestDetails,
): Promise<void>
requestPin 関数によって開始されたピン留めリクエストを停止します。
パラメータ
-
リクエスト フローを停止した理由の詳細が含まれます。
戻り値
-
Promise<void>
Chrome 96 以降 Chrome 148 以降の browser.*PIN ダイアログを閉じるリクエストが完了したときに解決される Promise を返します。
イベント
onCertificatesUpdateRequested
browser.certificateProvider.onCertificatesUpdateRequested.addListener(
callback: function,
)
このイベントは、setCertificates で設定された証明書が不十分な場合や、ブラウザが更新された情報をリクエストした場合に発生します。拡張機能は、更新された証明書のリストと受信した certificatesRequestId を指定して setCertificates を呼び出す必要があります。
パラメータ
-
callback
関数
callbackパラメータは次のようになります。(request: CertificatesUpdateRequest) => void
onSignatureRequested
browser.certificateProvider.onSignatureRequested.addListener(
callback: function,
)
このイベントは、ブラウザが setCertificates を介してこの拡張機能から提供された証明書を使用してメッセージに署名する必要があるたびに発生します。
拡張機能は、適切なアルゴリズムと秘密鍵を使用して request からの入力データに署名し、受信した signRequestId を指定して reportSignature を呼び出すことで、署名したデータを返す必要があります。
パラメータ
-
callback
関数
callbackパラメータは次のようになります。(request: SignatureRequest) => void
-
リクエスト
-