chrome.enterprise.platformKeys

説明

chrome.enterprise.platformKeys API を使用して鍵を生成し、その鍵の証明書をインストールします。この証明書はプラットフォームで管理され、TLS 認証やネットワーク アクセスに、または chrome.platformKeys を介して他の拡張機能で使用できます。

権限

enterprise.platformKeys

対象

ChromeOS のみ ポリシーが必要

コンセプトと使用方法

この 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

Chrome 110 以降

生成する鍵のタイプ。

列挙型

「RSA」

「ECDSA」

ChallengeKeyOptions

Chrome 110 以降

プロパティ

  • チャレンジ

    ArrayBuffer

    Verified Access Web API によって出力されたチャレンジ。

  • registerKey

    RegisterKeyOptions（省略可）

    存在する場合は、指定された scope のトークンにチャレンジ鍵を登録します。その後、この鍵を証明書に関連付けて、他の署名鍵と同様に使用できます。この関数を再度呼び出すと、指定した scope に新しいエンタープライズ キーが生成されます。

  • スコープ

    スコープ

    チャレンジする Enterprise キー。

RegisterKeyOptions

Chrome 110 以降

プロパティ

  • algorithm

    Algorithm

    登録された鍵が使用するアルゴリズム。

Scope

Chrome 110 以降

Enterprise ユーザーキーと Enterprise マシンキーのどちらを使用するか。

列挙型

"USER"

「MACHINE」

Token

プロパティ

  • id

    文字列

    この Token を一意に識別します。

    静的 ID は "user" と "system" で、それぞれプラットフォームのユーザー固有のハードウェア トークンとシステム全体のハードウェア トークンを参照します。他のトークン（他の識別子を持つトークン）は、enterprise.platformKeys.getTokens によって返される場合があります。

  • softwareBackedSubtleCrypto

    SubtleCrypto

    Chrome 97 以降

    WebCrypto の SubtleCrypto インターフェースを実装します。鍵の生成などの暗号オペレーションはソフトウェアでバックアップされます。鍵の保護、つまり抽出不可プロパティの実装はソフトウェアで行われるため、ハードウェアで保護された鍵よりも鍵の保護が弱くなります。

    抽出できない鍵のみを生成できます。サポートされる鍵のタイプは、RSASSA-PKCS1-V1_5 と RSA-OAEP で、modulusLength は最大 2,048 です。各 RSASSA-PKCS1-V1_5 鍵は、KeyPermissions ポリシーで拡張機能が許可リストに登録されている場合を除き、データの署名に 1 回しか使用できません。許可リストに登録されている場合は、鍵を無期限に使用できます。RSA-OAEP キーは、同じポリシーで許可リストに登録されている拡張機能によって、他のキーのアンラップに使用できます。

    特定の Token で生成された鍵は、他のトークンでは使用できません。また、window.crypto.subtle でも使用できません。同様に、window.crypto.subtle で作成された Key オブジェクトは、このインターフェースでは使用できません。

  • subtleCrypto

    SubtleCrypto

    WebCrypto の SubtleCrypto インターフェースを実装します。鍵の生成などの暗号オペレーションはハードウェアに依存しています。

    抽出できない鍵のみを生成できます。サポートされている鍵のタイプは、modulusLength が最大 2,048 の RSASSA-PKCS1-V1_5 と RSA-OAEP、namedCurve P-256 の ECDSA です。各 RSASSA-PKCS1-V1_5 鍵と ECDSA 鍵は、データの署名に 1 回しか使用できません。ただし、拡張機能が KeyPermissions ポリシーで許可リストに登録されている場合は、鍵を無期限に使用できます。RSA-OAEP キーは、同じポリシーで許可リストに登録されている拡張機能によって、他のキーのアンラップに使用できます。

    特定の Token で生成された鍵は、他のトークンでは使用できません。また、window.crypto.subtle でも使用できません。同様に、window.crypto.subtle で作成された Key オブジェクトは、このインターフェースでは使用できません。

メソッド

challengeKey()

Promise Chrome 110 以降 
chrome.enterprise.platformKeys.challengeKey(
  options: ChallengeKeyOptions,
  callback?: function,
)

challengeMachineKey と challengeUserKey に似ていますが、登録済みキーのアルゴリズムを指定できます。ハードウェア格納型の Enterprise Machine Key にチャレンジし、リモート構成証明プロトコルの一部としてレスポンスを出力します。ChromeOS でのみ使用でき、チャレンジの発行とレスポンスの検証の両方を行う Verified Access Web API と組み合わせて使用します。

Verified Access Web API による検証が正常に完了した場合、現在のデバイスが正当な ChromeOS デバイスであり、現在のデバイスが検証時に指定されたドメインによって管理されていること、現在のログイン ユーザーが検証時に指定されたドメインによって管理されていること、現在のデバイスの状態が企業のデバイス ポリシーに準拠していることを強く示唆します。たとえば、デバイスがデベロッパー モードであってはならないことをポリシーで指定できます。検証によって生成されたデバイス ID は、現在のデバイスのハードウェアに密接に関連付けられています。"user" スコープが指定されている場合、ID は現在ログインしているユーザーに厳密にバインドされます。

この関数は非常に制限されており、現在のデバイスが管理対象でない場合、現在のユーザーが管理対象でない場合、またはエンタープライズ デバイス ポリシーによって呼び出し元に対してこのオペレーションが明示的に有効にされていない場合、失敗します。チャレンジ キーは "system" トークンまたは "user" トークンに存在せず、他の API からはアクセスできません。

パラメータ

  • オプション

    ChallengeKeyOptions

    ChallengeKeyOptions で定義されたフィールドを含むオブジェクト。

  • callback

    function 省略可

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

    (response: ArrayBuffer) => void

    • レスポンス

      ArrayBuffer

      チャレンジ レスポンス。

戻り値

  • Promise<ArrayBuffer>

    Chrome 131 以降

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

challengeMachineKey()

Promise Chrome 50 以降 Chrome 110 以降非推奨
chrome.enterprise.platformKeys.challengeMachineKey(
  challenge: ArrayBuffer,
  registerKey?: boolean,
  callback?: function,
)

代わりに challengeKey を使用してください。

ハードウェア格納型の Enterprise Machine Key にチャレンジし、リモート構成証明プロトコルの一部としてレスポンスを出力します。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 です。この関数を再度呼び出すと、新しいエンタープライズ マシンキーが生成されます。

  • callback

    function 省略可

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

    (response: ArrayBuffer) => void

    • レスポンス

      ArrayBuffer

      チャレンジ レスポンス。

戻り値

  • Promise<ArrayBuffer>

    Chrome 131 以降

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

challengeUserKey()

Promise Chrome 50 以降 Chrome 110 以降非推奨
chrome.enterprise.platformKeys.challengeUserKey(
  challenge: ArrayBuffer,
  registerKey: boolean,
  callback?: function,
)

代わりに challengeKey を使用してください。

ハードウェアに保存されたエンタープライズ ユーザーキーにチャレンジし、リモート構成証明プロトコルの一部としてレスポンスを出力します。ChromeOS でのみ使用でき、チャレンジの発行とレスポンスの検証の両方を行う Verified Access Web API と組み合わせて使用します。Verified Access Web API による検証が正常に完了した場合は、* 現在のデバイスが正当な ChromeOS デバイスであるという強いシグナルとなります。* 現在のデバイスは、確認時に指定したドメインによって管理されています。* 現在ログインしているユーザーは、検証時に指定したドメインによって管理されています。* デバイスの現在の状態は、企業ユーザー ポリシーに準拠しています。たとえば、デバイスがデベロッパー モードであってはならないことをポリシーで指定できます。* 検証によって生成された公開鍵は、現在のデバイスのハードウェアと、現在ログインしているユーザーに厳密に関連付けられます。この関数は非常に制限されており、現在のデバイスが管理対象でない場合、現在のユーザーが管理対象でない場合、または企業ユーザー ポリシーによって呼び出し元に対してこのオペレーションが明示的に有効にされていない場合、失敗します。エンタープライズ ユーザーキーは "user" トークンに存在せず、他の API からはアクセスできません。

パラメータ

  • チャレンジ

    ArrayBuffer

    Verified Access Web API によって出力されたチャレンジ。

  • registerKey

    ブール値

    設定されている場合、現在のエンタープライズ ユーザーキーは "user" トークンに登録され、エンタープライズ ユーザーキーのロールが放棄されます。その後、この鍵を証明書に関連付けて、他の署名鍵と同様に使用できます。この鍵は 2,048 ビットの RSA です。この関数を再度呼び出すと、新しいエンタープライズ ユーザー キーが生成されます。

  • callback

    function 省略可

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

    (response: ArrayBuffer) => void

    • レスポンス

      ArrayBuffer

      チャレンジ レスポンス。

戻り値

  • Promise<ArrayBuffer>

    Chrome 131 以降

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

getCertificates()

Promise 
chrome.enterprise.platformKeys.getCertificates(
  tokenId: string,
  callback?: function,
)

指定されたトークンから使用可能なすべてのクライアント証明書のリストを返します。特定の認証に使用できるクライアント証明書の存在と有効期限を確認するために使用できます。

パラメータ

  • tokenId

    文字列

    getTokens によって返されるトークンの ID。

  • callback

    function 省略可

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

    (certificates: ArrayBuffer[]) => void

    • 証明書

      ArrayBuffer[]

      証明書のリスト。それぞれ X.509 証明書の DER エンコードです。

戻り値

  • Promise<ArrayBuffer[]>

    Chrome 131 以降

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

getTokens()

Promise 
chrome.enterprise.platformKeys.getTokens(
  callback?: function,
)

使用可能なトークンを返します。通常のユーザーのセッションでは、リストには常に id "user" を含むユーザーのトークンが含まれます。システム全体の TPM トークンが使用可能な場合、返されるリストには id "system" のシステム全体のトークンも含まれます。システム全体のトークンは、このデバイス（Chromebook などのデバイス）のすべてのセッションで同じになります。

パラメータ

  • callback

    function 省略可

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

    (tokens: Token[]) => void

    • トークン

      トークン[]

      使用可能なトークンのリスト。

戻り値

  • Promise<Token[]>

    Chrome 131 以降

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

importCertificate()

Promise 
chrome.enterprise.platformKeys.importCertificate(
  tokenId: string,
  certificate: ArrayBuffer,
  callback?: function,
)

認証済み鍵がすでにこのトークンに保存されている場合は、指定されたトークンに certificate をインポートします。認証リクエストが成功したら、この関数を使用して取得した証明書を保存し、オペレーティング システムとブラウザで認証できるようにする必要があります。

パラメータ

  • tokenId

    文字列

    getTokens によって返されるトークンの ID。

  • 証明書

    ArrayBuffer

    X.509 証明書の DER エンコード。

  • callback

    function 省略可

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

    () => void

戻り値

  • Promise<void>

    Chrome 131 以降

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

removeCertificate()

Promise 
chrome.enterprise.platformKeys.removeCertificate(
  tokenId: string,
  certificate: ArrayBuffer,
  callback?: function,
)

指定されたトークンから certificate を削除します（存在する場合）。古い証明書を削除して、認証時に考慮されないようにし、証明書の選択を煩雑にしないために使用します。証明書ストアのストレージを解放するために使用する必要があります。

パラメータ

  • tokenId

    文字列

    getTokens によって返されるトークンの ID。

  • 証明書

    ArrayBuffer

    X.509 証明書の DER エンコード。

  • callback

    function 省略可

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

    () => void

戻り値

  • Promise<void>

    Chrome 131 以降

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