chrome.enterprise.platformKeys

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

説明

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

権限

enterprise.platformKeys

対象

ChromeOS のみ ポリシーが必要

コンセプトと使用方法

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

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

  • id が "user" に等しいトークンを探します。このトークンを後で使用します。

  • generateKey() トークン メソッド（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 以降

生成する鍵のタイプ。

列挙型

「ECDSA」

ChallengeKeyOptions

Chrome 110 以降

プロパティ

  • チャレンジ

    ArrayBuffer

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

  • registerKey

    RegisterKeyOptions（省略可）

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

  • スコープ

    スコープ

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

RegisterKeyOptions

Chrome 110 以降

プロパティ

  • algorithm

    Algorithm

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

Scope

Chrome 110 以降

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

列挙型

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 のみです。各鍵はデータの署名に 1 回だけ使用できます。

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

メソッド

challengeKey()

Promise 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

    function 省略可

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

    (response: ArrayBuffer) => void

    • レスポンス

      ArrayBuffer

      チャレンジ レスポンス。

戻り値

  • Promise<ArrayBuffer>

    保留中

    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

    関数（省略可）

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

    (response: ArrayBuffer) => void

    • レスポンス

      ArrayBuffer

      チャレンジ レスポンス。

戻り値

  • Promise<ArrayBuffer>

    保留中

    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>

    保留中

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

getCertificates()

<ph type="x-smartling-placeholder"></ph> 約束 
chrome.enterprise.platformKeys.getCertificates(
  tokenId: string,
  callback?: function,
)

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

パラメータ

  • tokenId

    文字列

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

  • callback

    関数（省略可）

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

    (certificates: ArrayBuffer[]) => void

    • 証明書

      ArrayBuffer[]

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

戻り値

  • Promise<ArrayBuffer[]>

    保留中

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

getTokens()

<ph type="x-smartling-placeholder"></ph> 約束 
chrome.enterprise.platformKeys.getTokens(
  callback?: function,
)

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

パラメータ

  • callback

    関数（省略可）

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

    (tokens: Token[]) => void

    • トークン

      トークン[]

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

戻り値

  • Promise<Token[]>

    保留中

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

importCertificate()

<ph type="x-smartling-placeholder"></ph> 約束 
chrome.enterprise.platformKeys.importCertificate(
  tokenId: string,
  certificate: ArrayBuffer,
  callback?: function,
)

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

パラメータ

  • tokenId

    文字列

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

  • 証明書

    ArrayBuffer

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

  • callback

    function 省略可

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

    () => void

戻り値

  • Promise<void>

    保留中

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

removeCertificate()

<ph type="x-smartling-placeholder"></ph> 約束 
chrome.enterprise.platformKeys.removeCertificate(
  tokenId: string,
  certificate: ArrayBuffer,
  callback?: function,
)

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

パラメータ

  • tokenId

    文字列

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

  • 証明書

    ArrayBuffer

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

  • callback

    function 省略可

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

    () => void

戻り値

  • Promise<void>

    保留中

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