browser.enterprise.platformKeys

説明

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

権限

enterprise.platformKeys

対象

ChromeOS のみ ポリシーが必要

コンセプトと使用方法

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

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

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

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

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

  • sign() トークン メソッド（SubtleCrypto で定義）を使用して、証明書リクエストのデータの署名を作成します。

  • 証明書リクエストを完了し、認証局に送信します。

  • 証明書を受信した場合は、[enterprise.platformKeys.importCertificate()] を使用してインポートします。

次の例は、認証リクエストの作成と送信を除く、主要な API インタラクションを示しています。

function getUserToken(callback) {
  browser.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) {
  browser.enterprise.platformKeys.importCertificate(userToken.id, certificate);
}

getUserToken(generateAndSign);

型

Algorithm

Chrome 110 以降 Chrome 148 以降の browser.*

生成する鍵のタイプ。

列挙型

"RSA"

"ECDSA"

ChallengeKeyOptions

Chrome 110 以降 Chrome 148 以降の browser.*

プロパティ

  • チャレンジ

    ArrayBuffer

    確認済みアクセス Web API によって発行されたチャレンジ。

  • registerKey

    RegisterKeyOptions 省略可

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

  • スコープ

    スコープ

    本人確認を行うエンタープライズ キー。

RegisterKeyOptions

Chrome 110 以降 Chrome 148 以降の browser.*

プロパティ

  • algorithm

    Algorithm

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

Scope

Chrome 110 以降 Chrome 148 以降の browser.*

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

列挙型

"USER"

"MACHINE"

Token

プロパティ

  • id

    文字列

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

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

  • softwareBackedSubtleCrypto

    SubtleCrypto

    Chrome 97 以降 Chrome 148 以降の browser.*

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

    生成できるのは、抽出不可能な鍵のみです。サポートされている鍵タイプは、modulusLength が 2048 以下の RSASSA-PKCS1-V1_5 のみです。各鍵は、データの署名に 1 回だけ使用できます。ただし、KeyPermissions ポリシーで許可リストに登録されている拡張機能の場合は、鍵を無期限に使用できます。

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

  • subtleCrypto

    SubtleCrypto

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

    生成できるのは、抽出不可能な鍵のみです。サポートされている鍵タイプは、modulusLength が 2048 以下の RSASSA-PKCS1-V1_5 と、namedCurve が P-256 の ECDSA です。各鍵は、データの署名に最大 1 回使用できます。ただし、拡張機能が KeyPermissions ポリシーによって許可リストに登録されている場合は、鍵を無期限に使用できます。

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

メソッド

challengeKey()

Chrome 110 以降 Chrome 148 以降の browser.* 
browser.enterprise.platformKeys.challengeKey(
  options: ChallengeKeyOptions,
): Promise<ArrayBuffer>

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

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

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

パラメータ

戻り値

  • Promise<ArrayBuffer>

    Chrome 131 以降 Chrome 148 以降の browser.*

    チャレンジ レスポンスで解決される Promise を返します。

challengeMachineKey()

Chrome 50 以降 Chrome 148 以降の browser.* Chrome 110 以降は非推奨
browser.enterprise.platformKeys.challengeMachineKey(
  challenge: ArrayBuffer,
  registerKey?: boolean,
): Promise<ArrayBuffer>

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

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

パラメータ

  • チャレンジ

    ArrayBuffer

    確認済みアクセス Web API によって発行されたチャレンジ。

  • registerKey

    boolean 省略可

    Chrome 59 以降 Chrome 148 以降の browser.*

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

戻り値

  • Promise<ArrayBuffer>

    Chrome 131 以降 Chrome 148 以降の browser.*

    チャレンジ レスポンスで解決される Promise を返します。

challengeUserKey()

Chrome 50 以降 Chrome 148 以降の browser.* Chrome 110 以降は非推奨
browser.enterprise.platformKeys.challengeUserKey(
  challenge: ArrayBuffer,
  registerKey: boolean,
): Promise<ArrayBuffer>

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

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

パラメータ

  • チャレンジ

    ArrayBuffer

    確認済みアクセス Web API によって発行されたチャレンジ。

  • registerKey

    ブール値

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

戻り値

  • Promise<ArrayBuffer>

    Chrome 131 以降 Chrome 148 以降の browser.*

    チャレンジ レスポンスで解決される Promise を返します。

getCertificates()

browser.enterprise.platformKeys.getCertificates(
  tokenId: string,
): Promise<ArrayBuffer[]>

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

パラメータ

  • tokenId

    文字列

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

戻り値

  • Promise<ArrayBuffer[]>

    Chrome 131 以降 Chrome 148 以降の browser.*

    利用可能な証明書のリストで解決される Promise を返します。

getTokens()

browser.enterprise.platformKeys.getTokens(): Promise<Token[]>

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

戻り値

  • <Token[]> を約束

    Chrome 131 以降 Chrome 148 以降の browser.*

    利用可能なトークンのリストとともに getTokens によって呼び出されます。

importCertificate()

browser.enterprise.platformKeys.importCertificate(
  tokenId: string,
  certificate: ArrayBuffer,
): Promise<void>

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

パラメータ

  • tokenId

    文字列

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

  • 証明書

    ArrayBuffer

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

戻り値

  • Promise<void>

    Chrome 131 以降 Chrome 148 以降の browser.*

    このオペレーションが完了したときに解決される Promise を返します。

removeCertificate()

browser.enterprise.platformKeys.removeCertificate(
  tokenId: string,
  certificate: ArrayBuffer,
): Promise<void>

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

パラメータ

  • tokenId

    文字列

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

  • 証明書

    ArrayBuffer

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

戻り値

  • Promise<void>

    Chrome 131 以降 Chrome 148 以降の browser.*

    このオペレーションが完了したときに解決される Promise を返します。