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

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

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

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

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

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

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

ソースコード | パッケージ (NuGet) | API リファレンスドキュメント | 製品ドキュメント

作業の開始

前提条件

Azure サブスクリプション。 Microsoft Azure Attestation サービスを含む Azure サービスを使用するには、サブスクリプションが必要です。既存の Azure アカウントをお持ちでない場合は、無料試用版にサインアップするか、アカウントの作成時に Visual Studio サブスクリプション特典を使用できます。
既存の Azure Attestation インスタンス。または、各 Azure リージョンで使用可能な "共有プロバイダー" を使用できます。 Azure Attestation サービスインスタンスを作成する必要がある場合は、Azure Portal または Azure CLI を使用できます。

パッケージをインストールする

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

dotnet add package Azure.Security.Attestation --prerelease

クライアントを認証する

Microsoft Azure Attestation サービスを操作するには、構成証明クライアントまたは構成証明管理クライアントクラスのインスタンスを作成する必要があります。構成 証明インスタンス URL が必要です。この URL は、ポータルで "DNS 名" と表示され、クライアントオブジェクトをインスタンス化するための クライアントシークレット資格情報 (クライアント ID、クライアントシークレット、テナント ID) が必要です。

クライアントシークレット資格情報の認証は、この概要セクションで使用されていますが、 Azure ID で認証するその他の方法を見つけることができます。次に示す DefaultAzureCredential プロバイダー、または Azure SDK で提供されている他の資格情報プロバイダーを使用するには、Azure.Identity パッケージをインストールする必要があります。

dotnet add package 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 参照します。 Azure Attestation サービスは、SGX Quote/OE Report/OE Evidence のフィールドの最初の report_data 32 バイトが RuntimeData の SHA256 ハッシュと一致することを検証します。

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

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

スレッドセーフ

すべてのクライアントインスタンスメソッドがスレッドセーフであり、相互に独立していることを保証します (ガイドライン)。これにより、クライアントインスタンスの再利用に関する推奨事項は、スレッド間でも常に安全になります。

その他の概念

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

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

var options = new AttestationClientOptions();
return new AttestationClient(new Uri(endpoint), new DefaultAzureCredential(), options);

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

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

var client = new AttestationAdministrationClient(new Uri(endpoint), new DefaultAzureCredential());

AttestationResponse<string> policyResult = await client.GetPolicyAsync(AttestationType.SgxEnclave);
string result = policyResult.Value;

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

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

SetPolicy API では、構成証明サービスに送信されるポリシードキュメントと署名情報に基づいて JSON Web トークンが作成されます。

string attestationPolicy = "version=1.0; authorizationrules{=> permit();}; issuancerules{};";

X509Certificate2 policyTokenCertificate = new X509Certificate2(<Attestation Policy Signing Certificate>);
AsymmetricAlgorithm policyTokenKey = <Attestation Policy Signing Key>;

var setResult = client.SetPolicy(AttestationType.SgxEnclave, attestationPolicy, new AttestationTokenSigningKey(policyTokenKey, policyTokenCertificate));

クライアントは、構成証明サービスのエンクレーブによってポリシードキュメントが受信される前に、構成証明ポリシードキュメントが変更されていないことを確認できる必要があります。

PolicyResult には、サービスがポリシードキュメントを受信したことを確認するために使用できる 2 つのプロパティがあります。

PolicySigner - 呼び出しに SetPolicy 署名証明書が含まれている場合、これは呼び出し時 SetPolicy に指定された証明書になります。ポリシー署名者が設定されていない場合、これは null になります。
PolicyTokenHash - これは、サービスに送信される JSON Web トークンのハッシュです。

ハッシュを確認するために、クライアントは構成証明トークンを生成し、そのトークンから生成されたハッシュを確認できます。

// The SetPolicyAsync API will create an AttestationToken signed with the TokenSigningKey to transmit the policy.
// To verify that the policy specified by the caller was received by the service inside the enclave, we
// verify that the hash of the policy document returned from the Attestation Service matches the hash
// of an attestation token created locally.
TokenSigningKey signingKey = new TokenSigningKey(<Customer provided signing key>, <Customer provided certificate>)
var policySetToken = new AttestationToken(
    BinaryData.FromObjectAsJson(new StoredAttestationPolicy { AttestationPolicy = attestationPolicy }),
    signingKey);

using var shaHasher = SHA256Managed.Create();
byte[] attestationPolicyHash = shaHasher.ComputeHash(Encoding.UTF8.GetBytes(policySetToken.Serialize()));

Debug.Assert(attestationPolicyHash.SequenceEqual(setResult.Value.PolicyTokenHash.ToArray()));

SGX エンクレーブの構成証明

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

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

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

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

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

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

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

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

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

// Collect quote and runtime data from an SGX enclave.
// For the "Secure Key Release" scenario, the runtime data is normally a serialized asymmetric key.
// When the 'quote' (attestation evidence) is created specify the SHA256 hash of the runtime data when
// creating the evidence.
//
// When the generated evidence is created, the hash of the runtime data is included in the
// secured portion of the evidence.
//
// The Attestation service will validate that the Evidence is valid and that the SHA256 of the RuntimeData
// parameter is included in the evidence.
AttestationResponse<AttestationResult> attestationResult = client.AttestSgxEnclave(new AttestationRequest
{
    Evidence = BinaryData.FromBytes(binaryQuote),
    RuntimeData = new AttestationData(BinaryData.FromBytes(binaryRuntimeData), false),
});

// At this point, the EnclaveHeldData field in the attestationResult.Value property will hold the
// contain the input binaryRuntimeData.

// The token is now passed to the "relying party". The relying party will validate that the token was
// issued by the Attestation Service. It then extracts the asymmetric key from the EnclaveHeldData field.
// The relying party will then Encrypt it's "key" data using the asymmetric key and transmits it back
// to the enclave.
var encryptedData = SendTokenToRelyingParty(attestationResult.Token);

// Now the encrypted data can be passed into the enclave which can decrypt that data.

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

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

構成証明サービスから返されたトークンの検証に使用できる証明書を取得するには、を使用 GetSigningCertificatesAsync します。

var client = GetAttestationClient();

IReadOnlyList<AttestationSigner> signingCertificates = (await client.GetSigningCertificatesAsync()).Value;

トラブルシューティング

ほとんどの構成証明サービス操作では、役に立つ ErrorCodes で失敗した場合に RequestFailedException がスローされます。これらのエラーの多くは回復可能です。

try
{
    AttestationResponse<AttestationResult> attestationResult = client.AttestSgxEnclave(new AttestationRequest
    {
        Evidence = BinaryData.FromBytes(binaryQuote),
        RuntimeData = new AttestationData(BinaryData.FromBytes(binaryRuntimeData), false),
    });
}
catch (RequestFailedException ex)
    when (ex.ErrorCode == "InvalidParameter")
    {
    // Ignore invalid quote errors.
    }

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

次のステップ

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

共同作成

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

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

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

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

インプレッション数

次の方法で共有

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

作業の開始

前提条件

パッケージをインストールする

クライアントを認証する

資格情報の作成/取得

主要な概念

構成証明

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

ポリシー管理

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

分離モードと AAD モード

AttestationType

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

スレッドセーフ

その他の概念

例

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

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

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

SGX エンクレーブの構成証明

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

トラブルシューティング

次のステップ

共同作成

その他のリソース

次の方法で共有

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

作業の開始

前提条件

パッケージをインストールする

クライアントを認証する

資格情報の作成/取得

主要な概念

構成証明

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

ポリシー管理

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

分離モードと AAD モード

AttestationType

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

スレッド セーフ

その他の概念

例

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

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

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

SGX エンクレーブの構成証明

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

トラブルシューティング

次のステップ

共同作成

その他のリソース

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

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

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

スレッドセーフ

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