JavaScript 用Azure Attestation クライアントライブラリ - バージョン 1.0.0

[アーティクル]
04/05/2023

Microsoft Azure Attestation (MAA) サービスは、プラットフォームの信頼性と、その中で実行されているバイナリの整合性をリモートで検証するための統合ソリューションです。このサービスでは、トラステッドプラットフォームモジュール (TPM) によってサポートされるプラットフォームの構成証明と、Intel(tm) Software Guard Extensions (SGX) エンクレーブや仮想化ベースのセキュリティ (VBS) エンクレーブなどの信頼された実行環境 (TEEs) の状態を証明する機能がサポートされています。

構成証明は、ソフトウェアバイナリが信頼できるプラットフォームで適切にインスタンス化されたことを示すためのプロセスです。リモートの証明書利用者は、信頼できるハードウェアで上で実行されているのがこのような意図されたソフトウェアのみであるという確信を得ることができます。 Azure Attestation は、構成証明を目的とした、統合された顧客向けのサービスとフレームワークです。

Azure Attestation により、Azure Confidential Computing やインテリジェントエッジ保護などの最先端のセキュリティパラダイムが実現されます。これまで、マシンの場所、そのマシン上の仮想マシン (VM) の状況、その VM 上でエンクレーブが実行されている環境を個別に検証する機能がお客様から求められてきました。 Azure Attestation は、こうしたお客様や、それ以外の多くのお客様からの要望に応えるものです。

Azure Attestation は、コンピューティングエンティティから証拠を受け取り、それらを要求のセットに変換します。さらに、構成可能なポリシーに照らして検証し、要求ベースのアプリケーション (証明書利用者や監査機関など) のための暗号的証明を生成します。

Azure ライブラリの詳細なビューについては、 azure sdk typescript リリースに関するページを参照してください。

注: これは、Microsoft Azure Attestation サービスのプレビュー SDK です。 Azure Attestation サービスにアクセスするための重要なすべての機能が提供されます。これは"そのまま" と見なす必要があり、今後変更される可能性があるため、以前のバージョンとの互換性が損なわれる可能性があります。

主要リンク:

作業の開始

現在サポートされている環境

Node.js の LTS バージョン
Safari、Chrome、Edge、Firefox の最新バージョン。

詳細については、Microsoft のサポートポリシーを参照してください。

前提条件

Azure サブスクリプション
既存の Azure Attestation インスタンス。または、各 Azure リージョンで使用可能な "共有プロバイダー" を使用できます。 Azure Attestation サービスインスタンスを作成する必要がある場合は、Azure Portal または Azure CLI を使用できます。

@azure/attestation パッケージのインストール

NPM を使用して JavaScript 用の Microsoft Azure Attestation クライアントライブラリをインストールします。

npm install @azure/attestation

クライアントを認証する

Microsoft Azure Attestation サービスを操作するには、構成証明クライアントまたは構成証明管理クライアントクラスのインスタンスを作成する必要があります。 構成証明インスタンスの URL が必要です。これは、ポータルに表示される "構成証明 URI" であるか、共有構成証明プロバイダーのいずれかになります。また、構成証明管理クライアントを使用したり、API を呼び出したりするには、クライアント資格情報も attestTpm 必要です。クライアント資格情報では、クライアントオブジェクトをインスタンス化するために (クライアント ID、クライアントシークレット、テナント ID) が必要です。

この入門セクションでは、 DefaultAzureCredential プロバイダーを介してクライアントシークレット資格情報を使用して認証しますが、 @azure/ID パッケージを通じてより多くの認証メカニズムを提供します。 @azure/identity パッケージをインストールするには:

npm install @azure/identity

資格情報の作成/取得

次の Azure CLI スニペットを使用して、クライアントシークレットの資格情報を作成または取得します。

サービスプリンシパルを作成し、Azure リソースへのアクセスを構成します。

az ad sp create-for-rbac -n <your-application-name> --skip-assignment

出力:

{
  "appId": "generated-app-ID",
  "displayName": "dummy-app-name",
  "name": "http://dummy-app-name",
  "password": "random-password",
  "tenant": "tenant-ID"
}

サービスプリンシパル objectId をメモする

az ad sp show --id <appId> --query objectId

出力:

"<your-service-principal-object-id>"

上記で返された資格情報を使用して 、AZURE_CLIENT_ID (appId)、 AZURE_CLIENT_SECRET (パスワード)、 AZURE_TENANT_ID (テナント) 環境変数を設定します。次の例は、Powershell でこれを行う方法を示しています。

    $Env:AZURE_CLIENT_ID="generated-app-ID"
    $Env:AZURE_CLIENT_SECRET="random-password"
    $Env:AZURE_TENANT_ID="tenant-ID"

Azure Identity API とその使用方法の詳細については、「Azure Identity クライアントライブラリ」を参照してください。

主要な概念

このプレビュー SDK には、次の 4 つの主要な機能ファミリが用意されています。

SGX と TPM エンクレーブの構成証明。
MAA 構成証明トークン署名証明書の検出と検証。
構成証明ポリシーの管理。
構成証明ポリシー管理証明書管理 (はい、ポリシー管理管理)。

Microsoft Azure Attestation サービスは、"Isolated" と "AAD" の 2 つの異なるモードで実行されます。サービスが "Isolated" モードで実行されている場合、顧客は認証資格情報以外の追加情報を提供して、構成証明インスタンスの状態を変更する権限があることを確認する必要があります。

最後に、Microsoft Azure Attestation サービスが利用できる各リージョンでは、"共有" インスタンスがサポートされています。これは、Azure ベースラインに対する検証のみが必要な SGX エンクレーブを証明するために使用できます (共有プロバイダーに適用されるポリシーはありません)。 TPM 構成証明は、共有プロバイダーでは使用できません。共有インスタンスには AAD 認証が必要ですが、RBAC ポリシーはありません。有効な AAD ベアラートークンを持つ顧客は、共有インスタンスを使用して証明できます。

構成証明

SGX または TPM 構成証明は、信頼された実行環境から収集された証拠を検証して、その環境の Azure ベースラインと、その環境に適用される顧客定義のポリシーの両方を満たしていることを確認するプロセスです。

構成証明サービストークン署名証明書の検出と検証

Azure Attestation サービスの主要な運用上の保証の 1 つは、サービスが "TCB から運用可能に" 動作することです。つまり、Microsoft オペレーターがサービスの操作を改ざんしたり、クライアントから送信されたデータを破損させたりする方法はありません。この保証を保証するために、構成証明サービスのコアは Intel(tm) SGX エンクレーブで実行されます。

お客様がエンクレーブ内で操作が実際に実行されたことを確認できるようにするため、構成証明サービスからのほとんどの応答は JSON Web トークンでエンコードされます。これは、構成証明サービスのエンクレーブ内に保持されているキーによって署名されます。

このトークンは、指定されたインスタンスに対して MAA サービスによって発行された署名証明書によって署名されます。

サービスが SGX エンクレーブで実行されているリージョンで MAA サービスインスタンスが実行されている場合は、 oe_verify_attestation_certificate API を使用してサーバーによって発行された証明書を検証できます。

オブジェクトにはAttestationResponse、と valueの 2 つの主な属性がtoken含まれています。属性には token 構成証明サービスによって返される完全なトークンが含まれ、属性 value には JSON Web トークン応答の本文が含まれます。

ポリシー管理

各構成証明サービスインスタンスには、顧客が定義した追加の条件を定義するポリシーが適用されています。

構成証明ポリシーの詳細については、「構成証明ポリシー」を参照してください。

ポリシー管理証明書の管理

構成証明インスタンスが "Isolated" モードで実行されている場合、インスタンスを作成した顧客は、インスタンスの作成時にポリシー管理証明書を提供します。すべてのポリシー変更操作では、顧客が既存のポリシー管理証明書のいずれかを使用してポリシーデータに署名する必要があります。ポリシー管理証明書管理 API を使用すると、クライアントはポリシー管理証明書を "ロール" できます。

分離モードと AAD モード

各 Microsoft Azure Attestation サービスインスタンスは、"AAD" モードまたは "Isolated" モードで動作します。 MAA インスタンスが AAD モードで動作している場合は、構成証明インスタンスを作成した顧客が Azure Active Directory と Azure ロールベースのアクセス制御ポリシーで構成証明インスタンスへのアクセスを検証することを許可することを意味します。

AttestationType

Microsoft Azure Attestation サービスでは、環境に応じてさまざまな種類の証拠の構成証明がサポートされています。現在、MAA では、次の信頼された実行環境がサポートされています。

OpenEnclave - OpenEnclave oe_get_report または oe_get_evidence API を使用して構成証明の証拠が収集された SGX エンクレーブでコードを実行している Intel(tm) プロセッサ。
SgxEnclave - Intel SGX SDK を使用して構成証明の証拠が収集された SGX エンクレーブでコードを実行している Intel(tm) プロセッサ。
Tpm - プロセッサのトラステッドプラットフォームモジュールを使用して構成証明の証拠を提供する仮想化ベースのセキュリティ環境。

ランタイムデータと Inittime データ

RuntimeData は、Intel SGX Quote 生成ロジックまたは API に提示されるデータを oe_get_report/oe_get_evidence 参照します。構成証明 API の呼び出し元が属性をruntime_data指定した場合、Azure Attestation サービスは、SGX Quote/OE Report/OE Evidence のフィールドの最初の report_data 32 バイトがの runtime_dataSHA256 ハッシュと一致することを検証します。

InitTime データは、構成証明される SGX エンクレーブを構成するために使用されるデータを参照します。

InitTime データは、Azure DCsv2 シリーズの仮想マシンではサポートされていないことに注意してください。

その他の概念

クライアントインスタンスを作成する

既定の Azure 資格情報 (DefaultAzureCredential) を使用して、URI endpointで構成証明クライアントのインスタンスを作成します。

const credentials = new DefaultAzureCredential();
const client = new AttestationClient(endpoint, {credentials: credentials});

// Retrieve the set of attestation policy signers from the attestation client.
const attestationSigners = await client.getAttestationSigners();

API を呼び出 attestTpm していない場合は、構成証明クライアントにアクセスするための資格情報を指定する必要はありません。つまり、クライアントは次の方法で簡単に作成できます。

const client = new AttestationClient(endpoint);

// Retrieve the set of attestation policy signers from the attestation client.
const attestationSigners = await client.getAttestationSigners();

URI で構成証明管理クライアントのインスタンスを作成します endpoint。

管理クライアントには Azure 資格情報 が必要 であることに注意してください。

  const client = new AttestationAdministrationClient(endpoint, new DefaultAzureCredential());

  // Retrieve the SGX policy from the specified attestation instance.
  const policyResponse = await client.getPolicy(KnownAttestationType.SgxEnclave);

構成証明ポリシーを取得する

メソッドは getPolicy 、サービスから構成証明ポリシーを取得します。構成証明ポリシーは構成証明の種類ごとにインスタンス化され、パラメーターは AttestationType 取得するインスタンスの型を定義します。

const policyResult = await adminClient.getPolicy(attestationType);

// The text policy document is available in the `policyResult.body`
// property.

// The actual attestation token returned by the MAA service is available
// in `policyResult.token`.

指定した構成証明の種類の構成証明ポリシーを設定する

構成証明サービスインスタンスが分離モードで実行されている場合、set_policy API は署名証明書 (および秘密キー) を提供する必要があります。これは、呼び出し元が構成証明インスタンスのポリシーを変更する権限があることを検証するために使用できます。サービスインスタンスが AAD モードで実行されている場合、署名証明書とキーは省略可能です。

サービスインスタンスが AAD モードで実行されている場合、setPolicy の呼び出しは想定どおりに行われます。

const client = new AttestationAdministrationClient(endpoint, new DefaultAzureCredential());

const newPolicy = `<New Attestation Policy>`;

// Set the new attestation policy. Set the policy as an unsecured policy.
const setPolicyResult = await client.setPolicy(KnownAttestationType.SgxEnclave, newPolicy);

サービスインスタンスが分離モードで実行されている場合、setPolicy の呼び出しでは、クライアントがポリシー管理秘密キーと証明書のいずれかにアクセスできることを証明できる必要があります。

const client = new AttestationAdministrationClient(endpoint, new DefaultAzureCredential());

const newPolicy = `<New Policy Document>`;

// Set the new attestation policy. Set the policy as an secured policy.
const privateKey = <Retrieve isolated mode private key from storage>
const certificate = <Retrieve certificate associated with that private key>

const setPolicyResult = await client.setPolicy(
  KnownAttestationType.OpenEnclave,
  newPolicy,
  {
    privateKey: privateKey,
    certificate: certificate
  }
);

setPolicy API では、ポリシードキュメントcertificateに含まれる JSON Web トークンが作成され、で署名privateKeyされ、構成証明サービスに送信されます。

クライアントは、構成証明サービスのエンクレーブによってポリシードキュメントが受信される前に構成証明ポリシードキュメントが変更されていないことを確認する場合は、 PolicyResult objct で返されるプロパティを使用できます。このプロパティを使用して、サービスがポリシードキュメントを受信したことを確認できます。

policySigner - 呼び出しに setPolicy が certificate含まれている場合、この値は呼び出し時 setPolicy に指定された証明書になります。ポリシー署名者が設定されていない場合、これは null になります。
policyTokenHash - これは、setPolicy API のサービスに送信される JSON Web Signature のハッシュです。

ハッシュを確認するために、クライアントは構成証明ポリシートークン (構成証明ポリシーの設定に使用されるトークンを表すヘルパークラス) を作成し、そのトークンから生成されたハッシュを確認できます。

const expectedPolicy = createAttestationPolicyToken(
  `<Policy Document>`,
  privateKey,
  certificate);

// Use your favorite SHA256 hash generator function to create a hash of the
// stringized JWS.
const expectedHash = generateSha256Hash(expectedPolicy.serialize());

// The hash returned in expectedHash should match the value in
// `setResult.body.policyTokenHash`.

SGX を構成証明し、エンクレーブを開く

attestSgxEnclave SGX エンクレーブを証明するには、メソッドを使用します。

お客様が暗号化された環境と対話する主な課題の 1 つは、環境で実行されているコード ("エンクレーブコード") と安全に通信できるようにする方法です。

この問題の解決策の 1 つは、エンクレーブコードとのセキュリティで保護された通信を可能にするパターンである "セキュリティで保護されたキーリリース" と呼ばれるものです。

"Secure Key Release" パターンを実装するために、エンクレーブコードによってエフェメラル非対称キーが生成されます。次に、キーの公開部分を何らかの形式 (JSON Web キー、PEM、またはその他のシリアル化形式) にシリアル化します。

その後、エンクレーブコードは公開キーの SHA256 値を計算し、SGX Quote を生成するコードへの入力として渡します (OpenEnclave の場合は、 oe_get_evidence または oe_get_report)。

次に、クライアントは SGX 引用符とシリアル化されたキーを構成証明サービスに送信します。構成証明サービスは、引用符を検証し、キーのハッシュが引用符内に存在することを確認し、"構成証明トークン" を発行します。

クライアントは、その構成証明トークン (シリアル化されたキーを含む) をサードパーティの "証明書利用者" に送信できます。証明書利用者は、構成証明トークンが構成証明サービスによって作成されたことを検証します。そのため、シリアル化されたキーを使用して、サービスに送信する "証明書利用者" が保持するデータを暗号化できます。

この例では、要求に関連付けられている構成証明トークンを取得するために構成証明サービスを呼び出す一般的なパターンの 1 つを示します。

この例では、エンドポイントの構成証明 URI で構成された既存 AttestationClient のオブジェクトがあることを前提としています。また、構成証明する SGX エンクレーブ内から生成された OpenEnclave レポート (report) と、SGX 見積もりで参照される "ランタイムデータ" (binaryRuntimeData) があることを前提としています。

const attestationResult = await client.attestOpenEnclave(report, {
  runTimeData: binaryRuntimeData
});

また、構成証明サービスに送信されたが JSON データとして解釈されることを意図している可能性 binaryRuntimeData もあります。その場合、クライアントは構成証明 API 呼び出しでを指定 runTimeJson する必要があります。

const attestationResult = await client.attestOpenEnclave(report, {
  runTimeJson: binaryRuntimeData
});

同様に、Intel SDK を使用して "quote" を生成する場合は、次を使用して引用符を検証できます。

const attestationResult = await client.attestSgxEnclave(quote, {
  runTimeData: binaryRuntimeData
});

構成証明トークンの検証を実行する方法の詳細については、 MAA サービス構成証明のサンプルを参照してください。

トークン証明書を取得する

を使用して getSigningCertificates 、構成証明サービスから返されるトークンを検証するために使用できる証明書を取得します。この呼び出しでは、または API を呼び出している場合は必要ない、Azure 資格情報を使用してクライアントがattestSgxEnclaveattestOpenEnclave作成されることに注意してください

const credentials = new DefaultAzureCredential();
const client = new AttestationClient(endpoint, {credentials: credentials});

const attestationSigners = await client.getAttestationSigners();

console.log(`There are ${attestationSigners.length} signers`);

トラブルシューティング

ほとんどの構成証明サービス操作では、 Azure Core で定義されている例外が発生します。構成証明サービス API は、役に立つエラーコードを含むエラー時にを RestError スローします。これらのエラーの多くは回復可能です。

try {
  await client.attestSgxEnclave(openEnclaveReport);
} catch (error) {
  console.log(`Exception thrown for invalid request: ${error.message}`);
}

ログの記録

ログの記録を有効にすると、エラーに関する有用な情報を明らかにするのに役立つ場合があります。 HTTP 要求と応答のログを表示するには、環境変数 AZURE_LOG_LEVEL を info に設定します。または、@azure/logger で setLogLevel を呼び出して、実行時にログ記録を有効にすることもできます。

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

ログを有効にする方法の詳細については、@azure/logger パッケージに関するドキュメントを参照してください。

MAA サービスのその他のトラブルシューティング情報については、こちらを参照してください。

次の手順

Microsoft Azure Attestation サービスの詳細については、ドキュメントページを参照してください。

共同作成

このプロジェクトでは、共同作成と提案を歓迎しています。ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。詳細については、共同作成者ライセンス契約のサイトを参照してください。

pull request を送信すると、CLA を提供して PR (ラベル、コメントなど) を適宜装飾する必要があるかどうかを CLA ボットが自動的に決定します。ボットによって提供される手順にそのまま従ってください。この操作は、Microsoft の CLA を使用するすべてのリポジトリについて、1 回だけ行う必要があります。

このプロジェクトでは、Microsoft オープンソースの倫理規定を採用しています。詳しくは、「Code of Conduct FAQ (倫理規定についてよくある質問)」を参照するか、opencode@microsoft.com 宛てに質問またはコメントをお送りください。

これらのライブラリの構築、テスト、および貢献の詳細については、「 CONTRIBUTING.md 」を参照してください。

フィードバックの提供

バグが発生した場合、または提案がある場合は、プロジェクトの [問題 ] セクションで問題を報告してください。

Microsoft Azure SDK for Javascript

インプレッション数

次の方法で共有

JavaScript 用Azure Attestation クライアントライブラリ - バージョン 1.0.0

作業の開始

現在サポートされている環境

前提条件

@azure/attestation パッケージのインストール

クライアントを認証する

資格情報の作成/取得

主要な概念

構成証明

構成証明サービストークン署名証明書の検出と検証

ポリシー管理

ポリシー管理証明書の管理

分離モードと AAD モード

AttestationType

ランタイムデータと Inittime データ

その他の概念

例

クライアントインスタンスを作成する

構成証明ポリシーを取得する

指定した構成証明の種類の構成証明ポリシーを設定する

SGX を構成証明し、エンクレーブを開く

トークン証明書を取得する

トラブルシューティング

ログの記録

次の手順

共同作成

フィードバックの提供

フィードバック

その他のリソース

次の方法で共有

JavaScript 用Azure Attestation クライアント ライブラリ - バージョン 1.0.0

作業の開始

現在サポートされている環境

前提条件

@azure/attestation パッケージのインストール

クライアントを認証する

資格情報の作成/取得

主要な概念

構成証明

構成証明サービス トークン署名証明書の検出と検証

ポリシー管理

ポリシー管理証明書の管理

分離モードと AAD モード

AttestationType

ランタイム データと Inittime データ

その他の概念

例

クライアント インスタンスを作成する

構成証明ポリシーを取得する

指定した構成証明の種類の構成証明ポリシーを設定する

SGX を構成証明し、エンクレーブを開く

トークン証明書を取得する

トラブルシューティング

ログの記録

次の手順

共同作成

フィードバックの提供

関連プロジェクト

フィードバック

その他のリソース

JavaScript 用Azure Attestation クライアントライブラリ - バージョン 1.0.0

構成証明サービストークン署名証明書の検出と検証

ランタイムデータと Inittime データ

クライアントインスタンスを作成する