説明
chrome.enterprise.platformKeys API を使用して鍵を生成し、その鍵の証明書をインストールします。この証明書はプラットフォームで管理され、TLS 認証やネットワーク アクセスに、または chrome.platformKeys を介して他の拡張機能で使用できます。
権限
enterprise.platformKeys対象
コンセプトと使用方法
この API を使用してクライアント証明書を登録する一般的な手順は次のとおりです。
enterprise.platformKeys.getTokens()を使用して、利用可能なすべてのトークンを取得します。idが"user"に等しいトークンを見つけます。このトークンを後で使用します。generateKey()トークン メソッド（SubtleCrypto で定義）を使用して鍵ペアを生成します。これにより、キーのハンドルが返されます。exportKey()トークン メソッド（SubtleCrypto で定義）を使用して公開鍵をエクスポートします。sign()トークン メソッド（SubtleCrypto で定義）を使用して、認証リクエストのデータの署名を作成します。認証リクエストを完了し、認証機関に送信します。
証明書を受信したら、[
enterprise.platformKeys.importCertificate()`[3] を使用してインポートします。
次に、証明書リクエストの作成と送信を除く、主な API 連携を示す例を示します。
function getUserToken(callback) {
chrome.enterprise.platformKeys.getTokens(function(tokens) {
for (var i = 0; i < tokens.length; i++) {
if (tokens[i].id == "user") {
callback(tokens[i]);
return;
}
}
callback(undefined);
});
}
function generateAndSign(userToken) {
var data = new Uint8Array([0, 5, 1, 2, 3, 4, 5, 6]);
var algorithm = {
name: "RSASSA-PKCS1-v1_5",
// RsaHashedKeyGenParams
modulusLength: 2048,
publicExponent:
new Uint8Array([0x01, 0x00, 0x01]), // Equivalent to 65537
hash: {
name: "SHA-256",
}
};
var cachedKeyPair;
userToken.subtleCrypto.generateKey(algorithm, false, ["sign"])
.then(function(keyPair) {
cachedKeyPair = keyPair;
return userToken.subtleCrypto.exportKey("spki", keyPair.publicKey);
},
console.log.bind(console))
.then(function(publicKeySpki) {
// Build the Certification Request using the public key.
return userToken.subtleCrypto.sign(
{name : "RSASSA-PKCS1-v1_5"}, cachedKeyPair.privateKey, data);
},
console.log.bind(console))
.then(function(signature) {
// Complete the Certification Request with |signature|.
// Send out the request to the CA, calling back
// onClientCertificateReceived.
},
console.log.bind(console));
}
function onClientCertificateReceived(userToken, certificate) {
chrome.enterprise.platformKeys.importCertificate(userToken.id, certificate);
}
getUserToken(generateAndSign);
型
Algorithm
生成する鍵のタイプ。
列挙型
"RSA"
"ECDSA"
ChallengeKeyOptions
プロパティ
-
チャレンジ
ArrayBuffer
Verified Access Web API によって発行されたチャレンジ。
-
registerKey
存在する場合、指定された
scopeのトークンを使用して、チャレンジされたキーを登録します。鍵は証明書に関連付けられ、他の署名鍵と同様に使用できます。この関数を呼び出すと、指定されたscopeに新しいエンタープライズ キーが生成されます。 -
スコープ
どの Enterprise キーをチャレンジするか。
RegisterKeyOptions
プロパティ
-
algorithm
登録された鍵が使用するアルゴリズム。
Scope
Enterprise User Key と Enterprise Machine Key のどちらを使用するか。
列挙型
"USER"
"MACHINE"
Token
プロパティ
-
id
文字列
この
Tokenを一意に識別します。静的 ID は
"user"と"system"で、それぞれプラットフォームのユーザー固有のハードウェア トークンとシステム全体のハードウェア トークンを参照します。他のトークン（他の識別子を含む）はenterprise.platformKeys.getTokensによって返される可能性があります。 -
softwareBackedSubtleCrypto
SubtleCrypto
Chrome 97 以降WebCrypto の SubtleCrypto インターフェースを実装します。鍵の生成などの暗号オペレーションは、ソフトウェアでサポートされています。鍵の保護、つまり抽出不可プロパティの実装はソフトウェアで行われるため、鍵の保護はハードウェアにより保護された鍵よりも弱くなります。
抽出不可能な鍵のみを生成できます。サポートされている鍵のタイプは、RSASSA-PKCS1-V1_5 と RSA-OAEP（Chrome バージョン 135 以降）で、
modulusLengthは最大 2,048 です。各 RSASSA-PKCS1-V1_5 鍵は、KeyPermissions ポリシーで拡張機能が許可リストに登録されていない限り、データの署名に 1 回しか使用できません。許可リストに登録されている場合は、鍵を無期限で使用できます。RSA-OAEP 鍵は Chrome バージョン 135 以降でサポートされており、同じポリシーで許可リストに登録された拡張機能が他の鍵のラップ解除に使用できます。特定の
Tokenで生成された鍵は、他のトークンでは使用できません。また、window.crypto.subtleでも使用できません。同様に、window.crypto.subtleで作成されたKeyオブジェクトはこのインターフェースでは使用できません。 -
subtleCrypto
SubtleCrypto
WebCrypto の SubtleCrypto インターフェースを実装します。鍵の生成などの暗号オペレーションは、ハードウェアに組み込まれています。
抽出不可能な鍵のみを生成できます。サポートされている鍵のタイプは、
modulusLengthが最大 2,048 の RSASSA-PKCS1-V1_5 と RSA-OAEP（Chrome バージョン 135 以降）、namedCurveP-256 の ECDSA です。KeyPermissions ポリシーで拡張機能が許可リストに登録されていない限り、各 RSASSA-PKCS1-V1_5 鍵と ECDSA 鍵はデータの署名に 1 回しか使用できません。許可リストに登録されている場合は、鍵を無期限で使用できます。RSA-OAEP 鍵は Chrome バージョン 135 以降でサポートされており、同じポリシーで許可リストに登録された拡張機能が他の鍵のラップ解除に使用できます。特定の
Tokenで生成された鍵は、他のトークンでは使用できません。また、window.crypto.subtleでも使用できません。同様に、window.crypto.subtleで作成されたKeyオブジェクトはこのインターフェースでは使用できません。
メソッド
challengeKey()
chrome.enterprise.platformKeys.challengeKey(
options: ChallengeKeyOptions,
): Promise<ArrayBuffer>
challengeMachineKey や challengeUserKey と似ていますが、登録された鍵のアルゴリズムを指定できます。ハードウェア格納型エンタープライズ マシンキーにチャレンジし、リモート構成証明プロトコルの一部としてレスポンスを送信します。ChromeOS でのみ有効で、チャレンジを発行してレスポンスを検証する Verified Access Web API と組み合わせて使用します。
確認済みアクセス Web API による検証が成功すると、現在のデバイスが正規の ChromeOS デバイスであること、現在のデバイスが検証時に指定されたドメインによって管理されていること、現在のログイン ユーザーが検証時に指定されたドメインによって管理されていること、現在のデバイスの状態が企業デバイス ポリシーに準拠していることを示す強力なシグナルとなります。たとえば、ポリシーでデバイスがデベロッパー モードでないことを指定できます。検証によって出力されるデバイス ID は、現在のデバイスのハードウェアに厳密にバインドされます。"user" スコープが指定されている場合、ID は現在ログインしているユーザーにも厳密にバインドされます。
この関数は厳しく制限されており、現在のデバイスが管理対象でない場合、現在のユーザーが管理対象でない場合、またはこのオペレーションがエンタープライズ デバイス ポリシーによって呼び出し元に対して明示的に有効にされていない場合は失敗します。チャレンジされたキーは "system" トークンまたは "user" トークンに存在せず、他の API からアクセスできません。
パラメータ
-
オプション
ChallengeKeyOptionsで定義されているフィールドを含むオブジェクト。
戻り値
-
Promise<ArrayBuffer>
Chrome 131 以降
challengeMachineKey()
chrome.enterprise.platformKeys.challengeMachineKey(
challenge: ArrayBuffer,
registerKey?: boolean,
): Promise<ArrayBuffer>
代わりに challengeKey を使用してください。
ハードウェア格納型エンタープライズ マシンキーにチャレンジし、リモート構成証明プロトコルの一部としてレスポンスを送信します。ChromeOS でのみ有効で、チャレンジを発行してレスポンスを検証する Verified Access Web API と組み合わせて使用します。Verified Access Web API による検証が成功すると、次のすべてのことが強く示されます。* 現在のデバイスは正規の ChromeOS デバイスである。* 現在のデバイスが、確認時に指定したドメインによって管理されている。* 現在ログインしているユーザーが、検証時に指定されたドメインによって管理されている。* 現在のデバイスの状態が企業デバイス ポリシーに準拠している。たとえば、ポリシーでデバイスがデベロッパー モードでないことを指定できます。* 検証によって出力されるデバイス ID は、現在のデバイスのハードウェアに厳密にバインドされます。この関数は厳しく制限されており、現在のデバイスが管理対象でない場合、現在のユーザーが管理対象でない場合、またはこのオペレーションがエンタープライズ デバイス ポリシーによって呼び出し元に対して明示的に有効にされていない場合は失敗します。エンタープライズ マシンキーは "system" トークンに存在せず、他の API からアクセスできません。
パラメータ
-
チャレンジ
ArrayBuffer
Verified Access Web API によって発行されたチャレンジ。
-
registerKey
ブール値（省略可）
Chrome 59+設定されている場合、現在のエンタープライズ マシンキーが
"system"トークンに登録され、エンタープライズ マシンキーのロールが放棄されます。鍵は証明書に関連付けられ、他の署名鍵と同様に使用できます。この鍵は 2,048 ビットの RSA です。この関数を呼び出すと、新しい Enterprise Machine Key が生成されます。
戻り値
-
Promise<ArrayBuffer>
Chrome 131 以降
challengeUserKey()
chrome.enterprise.platformKeys.challengeUserKey(
challenge: ArrayBuffer,
registerKey: boolean,
): Promise<ArrayBuffer>
代わりに challengeKey を使用してください。
ハードウェア格納型エンタープライズ ユーザーキーをチャレンジし、リモート構成証明プロトコルの一部としてレスポンスを出力します。ChromeOS でのみ有効で、チャレンジを発行してレスポンスを検証する Verified Access Web API と組み合わせて使用します。Verified Access Web API による検証が成功すると、次のすべてのことが強く示されます。* 現在のデバイスは正規の ChromeOS デバイスである。* 現在のデバイスが、確認時に指定したドメインによって管理されている。* 現在ログインしているユーザーが、検証時に指定されたドメインによって管理されている。* 現在のデバイスの状態が企業ユーザー ポリシーに準拠している。たとえば、ポリシーでデバイスがデベロッパー モードでないことを指定できます。* 検証によって出力される公開鍵は、現在のデバイスのハードウェアと現在のログイン ユーザーに厳密にバインドされます。この関数は厳しく制限されており、現在のデバイスが管理対象でない場合、現在のユーザーが管理対象でない場合、またはこのオペレーションが企業ユーザー ポリシーによって呼び出し元に対して明示的に有効になっていない場合は失敗します。Enterprise User Key は "user" トークンに存在せず、他の API からアクセスすることはできません。
パラメータ
-
チャレンジ
ArrayBuffer
Verified Access Web API によって発行されたチャレンジ。
-
registerKey
ブール値
設定されている場合、現在の Enterprise User Key は
"user"トークンに登録され、Enterprise User Key ロールを放棄します。鍵は証明書に関連付けられ、他の署名鍵と同様に使用できます。この鍵は 2,048 ビットの RSA です。この関数を呼び出すと、新しいエンタープライズ ユーザーキーが生成されます。
戻り値
-
Promise<ArrayBuffer>
Chrome 131 以降
getCertificates()
chrome.enterprise.platformKeys.getCertificates(
tokenId: string,
): Promise<ArrayBuffer[]>
指定されたトークンから利用可能なすべてのクライアント証明書のリストを返します。特定の認証に使用できるクライアント証明書の存在と有効期限を確認するために使用できます。
パラメータ
-
tokenId
文字列
getTokensによって返されるトークンの ID。
戻り値
-
Promise<ArrayBuffer[]>
Chrome 131 以降
getTokens()
chrome.enterprise.platformKeys.getTokens(): Promise<Token[]>
使用可能なトークンを返します。一般ユーザーのセッションでは、リストには常に id "user" を含むユーザーのトークンが含まれます。システム全体の TPM トークンが利用可能な場合、返されるリストには id "system" を含むシステム全体のトークンも含まれます。システム全体のトークンは、このデバイス（Chromebook など）のすべてのセッションで同じになります。
戻り値
-
Promise<Token[]>
Chrome 131 以降
importCertificate()
chrome.enterprise.platformKeys.importCertificate(
tokenId: string,
certificate: ArrayBuffer,
): Promise<void>
認証済み鍵がこのトークンにすでに保存されている場合、certificate を指定されたトークンにインポートします。認証リクエストが成功したら、この関数を使用して取得した証明書を保存し、認証のためにオペレーティング システムとブラウザで使用できるようにする必要があります。
パラメータ
-
tokenId
文字列
getTokensによって返されるトークンの ID。 -
証明書
ArrayBuffer
X.509 証明書の DER エンコード。
戻り値
-
Promise<void>
Chrome 131 以降
removeCertificate()
chrome.enterprise.platformKeys.removeCertificate(
tokenId: string,
certificate: ArrayBuffer,
): Promise<void>
指定されたトークンに certificate が存在する場合は削除します。認証時に考慮されず、証明書の選択肢が煩雑にならないように、古い証明書を削除するために使用する必要があります。証明書ストアのストレージを解放するために使用する必要があります。
パラメータ
-
tokenId
文字列
getTokensによって返されるトークンの ID。 -
証明書
ArrayBuffer
X.509 証明書の DER エンコード。
戻り値
-
Promise<void>
Chrome 131 以降