chrome.enterprise.platformKeys

この API は、ポリシーによってインストールされた拡張機能専用です。

説明

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

権限

enterprise.platformKeys

対象

<ph type="x-smartling-placeholder"></ph> ChromeOS のみ <ph type="x-smartling-placeholder"></ph> <ph type="x-smartling-placeholder"></ph> ポリシーが必要

コンセプトと使用方法

通常、この API を使用してクライアント証明書を登録する手順は次のとおりです。

  • enterprise.platformKeys.getTokens() を使用して、利用可能なすべてのトークンを取得します。

  • id が "user" と等しいトークンを見つけます。このトークンを後で使用します。

  • generateKey() Token メソッド（SubtleCrypto で定義）を使用して鍵ペアを生成します。これにより、鍵のハンドルが返されます。

  • exportKey() Token メソッド（SubtleCrypto で定義）を使用して公開鍵をエクスポートします。

  • sign() Token メソッド（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 に新しいエンタープライズ キーが生成されます。

  • スコープ

    範囲

    チャレンジするエンタープライズ キー。

RegisterKeyOptions

Chrome 110 以降

プロパティ

  • algorithm

    Algorithm

    登録済みの鍵が使用するアルゴリズム。

Scope

Chrome 110 以降

エンタープライズ ユーザーキーとエンタープライズ マシンキーのどちらを使用するか。

列挙型

「ユーザー」

"MACHINE"

Token

プロパティ

  • id

    文字列

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

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

  • softwareBackedSubtleCrypto

    SubtleCrypto

    Chrome 97 以降

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

    modulusLength が最大 2,048 の解凍不可の RSASSA-PKCS1-V1_5 鍵のみを生成できます。各鍵は、データの署名に一度に使用できます。

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

  • subtleCrypto

    SubtleCrypto

    WebCrypto の SubtleCrypto インターフェースを実装します。鍵生成を含む暗号オペレーションは、ハードウェア格納型です。

    生成できるのは、modulusLength が最大 2,048 の RSASSA-PKCS1-V1_5 鍵と、namedCurve P-256 の ECDSA 鍵のみです。各鍵は、データの署名に一度に使用できます。

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

メソッド

challengeKey()

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

challengeMachineKey や challengeUserKey に似ていますが、登録済み鍵のアルゴリズムを指定できます。ハードウェア格納型のエンタープライズ マシンキーにチャレンジし、リモート構成証明プロトコルの一部としてレスポンスを発行します。ChromeOS でのみ有効で、本人確認の発行とレスポンスの検証を行う Verified Access Web API と組み合わせて使用します。

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

この機能は厳しく制限されているため、現在のデバイスが管理されていない場合、現在のユーザーが管理されていない場合、またはこの操作が企業のデバイス ポリシーによって呼び出し元に対して明示的に有効になっていない場合は失敗します。チャレンジ対象の鍵が "system" トークンまたは "user" トークンに存在しておらず、他の API からアクセスできない。

パラメータ

  • オプション

    ChallengeKeyOptions

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

  • callback

    関数

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

    (response: ArrayBuffer) => void

    • レスポンス

      ArrayBuffer

      チャレンジ レスポンス。

challengeMachineKey()

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

代わりに 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 です。その後、この関数を呼び出すと、新しいエンタープライズ マシンキーが生成されます。

  • callback

    関数

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

    (response: ArrayBuffer) => void

    • レスポンス

      ArrayBuffer

      チャレンジ レスポンス。

challengeUserKey()

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

    関数

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

    (response: ArrayBuffer) => void

    • レスポンス

      ArrayBuffer

      チャレンジ レスポンス。

getCertificates()

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

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

パラメータ

  • tokenId

    文字列

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

  • callback

    関数

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

    (certificates: ArrayBuffer[]) => void

    • 証明書

      ArrayBuffer[]

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

getTokens()

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

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

パラメータ

  • callback

    関数

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

    (tokens: Token[]) => void

    • トークン

      トークン[]

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

importCertificate()

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

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

パラメータ

  • tokenId

    文字列

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

  • 証明書

    ArrayBuffer

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

  • callback

    関数（省略可）

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

    () => void

removeCertificate()

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

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

パラメータ

  • tokenId

    文字列

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

  • 証明書

    ArrayBuffer

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

  • callback

    関数（省略可）

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

    () => void