chrome.enterprise.platformKeys

説明

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

権限

enterprise.platformKeys

対象

ChromeOS のみ ポリシーが必要

コンセプトと使用方法

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

生成する鍵のタイプ。

Enum

ChallengeKeyOptions

Chrome 110 以降

プロパティ

  • チャレンジ

    ArrayBuffer

    Verified Access Web API が出力するチャレンジ。

  • registerKey

    RegisterKeyOptions 省略可

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

  • スコープ

    範囲

    挑戦すべきエンタープライズ キー。

RegisterKeyOptions

Chrome 110 以降

プロパティ

  • algorithm

    Algorithm

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

Scope

Chrome 110 以降

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

Enum

"MACHINE"

Token

プロパティ

  • id

    文字列

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

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

  • softwareBackedSubtleCrypto

    SubtleCrypto

    Chrome 97 以降

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

    生成できるのは、modulusLength が最大 2,048 個の RSASSA-PKCS1-V1_5 鍵のみです。データの署名に各鍵を 1 回だけ使用できます。

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

  • subtleCrypto

    SubtleCrypto

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

    生成できるのは、抽出不可能な RSASSA-PKCS1-V1_5 鍵（modulusLength が 2048 まで）と ECDSA の namedCurve P-256 のみです。データの署名に各鍵を 1 回だけ使用できます。

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

Methods

challengeKey()

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

challengeMachineKey や challengeUserKey に似ていますが、登録済みの鍵のアルゴリズムを指定できます。ハードウェア格納型エンタープライズ マシンキーにチャレンジし、リモート構成証明プロトコルの一部としてレスポンスを送信します。Chrome OS で、本人確認とレスポンスの検証の両方を行う 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 を使用してください。

ハードウェア格納型エンタープライズ マシンキーにチャレンジし、リモート構成証明プロトコルの一部としてレスポンスを送信します。Chrome OS で、本人確認とレスポンスの検証の両方を行う 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 を使用してください。

ハードウェア格納型エンタープライズ ユーザーキーにチャレンジし、リモート構成証明プロトコルの一部としてレスポンスを出力します。Chrome OS で、本人確認とレスポンスの検証の両方を行う Verified Access Web API と組み合わせて使用します。Verified Access Web API による検証が成功すると、次のすべてを示す強力なシグナルとなります。* 現在のデバイスが正規の ChromeOS デバイスである。* 現在のデバイスは、確認時に指定されたドメインによって管理されています。* 現在ログインしているユーザーは、確認時に指定されたドメインによって管理されます。* デバイスの現在の状態が企業のユーザー ポリシーに準拠していること。たとえば、ポリシーにより、デバイスがデベロッパー モードにならないように指定できます。* 検証によって発行される公開鍵は、現在のデバイスのハードウェアと、現在ログインしているユーザーに厳格にバインドされます。この機能は厳しく制限されており、現在のデバイスが管理されていない場合、現在のユーザーが管理されていない場合、または企業ユーザー ポリシーによって呼び出し元に対してこの操作が明示的に有効化されていない場合、失敗します。エンタープライズ ユーザーキーは "user" トークン内には存在せず、他の API からはアクセスできません。

パラメータ

  • チャレンジ

    ArrayBuffer

    Verified Access Web API が出力するチャレンジ。

  • registerKey

    boolean

    設定すると、現在のエンタープライズ ユーザーキーは "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

    • certificates

      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