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

[アーティクル]
10/21/2023

Microsoft Azure Attestation (プレビュー) は、プラットフォームの信頼性とその内部で実行されているバイナリの整合性をリモートで検証するための統合ソリューションです。このサービスでは、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 サービスにアクセスするために不可欠なすべての機能が提供されますが、適切に動作するにはかなりの量のインフラストラクチャが必要です。

作業の開始

パッケージを組み込む

BOM ファイルを含める

ライブラリの一般提供 (GA) バージョンに依存するには、azure-sdk-bom をプロジェクトに含めてください。次のスニペットでは、{bom_version_to_target} プレースホルダーをバージョン番号に置き換えます。 BOM の詳細については、 AZURE SDK BOM README に関するページを参照してください。

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

次に、次に示すようにバージョンタグを使用せずに、依存関係セクションに直接依存関係を含めます。

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-security-attestation</artifactId>
  </dependency>
</dependencies>

直接依存関係を含める

BOM に存在しないライブラリの特定のバージョンに依存する場合は、次のように直接依存関係をプロジェクトに追加します。

<!-- Install the Azure Attestation SDK -->
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-security-attestation</artifactId>
    <version>1.1.18</version>
</dependency>

前提条件

Java Development Kit (JDK) バージョン 8 以降。
Azure サブスクリプション
既存のAzure Attestation インスタンス。構成証明インスタンスを作成する必要がある場合は、Azure Cloud Shellを使用して、この Azure CLI コマンドを使用して作成できます。と <your-instance-name> を独自の一意の名前に置き換えます<your-resource-group-name>。

az attestation create --resource-group <your-resource-group-name> --name <your-instance-name>

クライアントを認証する

Azure Attestation サービスと対話するには、クライアントが Azure Active Directory ベアラートークンをサービスに提示する必要があります。

ベアラートークンを提供する最も簡単な方法は、クライアントシークレットの資格情報を指定して認証方法を使用 DefaultAzureCredential することです。この概要セクションでは使用されていますが、 azure-identity で認証する方法は他にも見つかります。

主要な概念

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

このプレビュー SDK には、次の 4 つの主要なクライアントの種類が用意されています。

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

各構成証明インスタンスは、次の 2 つの異なる動作モードのいずれかで動作します。

AAD モード。
分離モード

"AAD" モードでは、サービスへのアクセスは、Azure ロールベースのAccess Controlによってのみ制御されます。 "Isolated" モードでは、クライアントは、クライアントがサービスの変更を許可されていることを証明する追加の証拠を提供することが期待されます。

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

構成証明

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

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

MAA サービスからのほとんどの応答は、JSON Web トークンの形式で表されます。このトークンは、指定されたインスタンスに対して MAA サービスによって発行された署名証明書によって署名されます。サービスが SGX エンクレーブで実行されているリージョンで MAA サービスインスタンスが実行されている場合、サーバーによって発行された証明書は、oe_verify_attestation_certificate() API を使用して検証できます。

ポリシー管理

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

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

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

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

同期構成証明クライアントをインスタンス化する

クラスは AttestationClientBuilder 、構成証明クライアントのインスタンスを作成するために使用されます。

AttestationClientBuilder attestationBuilder = new AttestationClientBuilder();
// Note that the "attest" calls do not require authentication.
AttestationClient client = attestationBuilder
    .endpoint(endpoint)
    .buildClient();

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

証明書のセットを取得するために使用 listAttestationSigners します。証明書は、構成証明サービスから返されるトークンを検証するために使用できます。通常、構成証明 SDK は構成証明サービスとの対話の一環として検証を実行するため、この情報は必要ありません。ただし、API は完全性のために提供され、お客様が独立して構成証明の結果を検証できるように提供されます。

AttestationSignerCollection certs = client.listAttestationSigners();

certs.getAttestationSigners().forEach(cert -> {
    System.out.println("Found certificate.");
    if (cert.getKeyId() != null) {
        System.out.println("    Certificate Key ID: " + cert.getKeyId());
    } else {
        System.out.println("    Signer does not have a Key ID");
    }
    cert.getCertificates().forEach(chainElement -> {
        System.out.println("        Cert Subject: " + chainElement.getSubjectDN().getName());
        System.out.println("        Cert Issuer: " + chainElement.getIssuerDN().getName());
    });
});

SGX エンクレーブを構成証明する

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

BinaryData decodedRuntimeData = BinaryData.fromBytes(SampleCollateral.getRunTimeData());
BinaryData sgxQuote = BinaryData.fromBytes(SampleCollateral.getSgxEnclaveQuote());

// Attest evidence from an OpenEnclave enclave specifying runtime data which should be
// interpreted as binary data.
AttestationResult result = client.attestSgxEnclave(new AttestationOptions(sgxQuote)
    .setRunTimeData(
        new AttestationData(decodedRuntimeData, AttestationDataInterpretation.BINARY)));

String issuer = result.getIssuer();

System.out.println("Attest Sgx Enclave completed. Issuer: " + issuer);
System.out.printf("Runtime Data Length: %d\n", result.getEnclaveHeldData().getLength());

同期管理クライアントをインスタンス化する

すべての管理クライアントが認証されます。

AttestationAdministrationClientBuilder attestationBuilder = new AttestationAdministrationClientBuilder();
// Note that the "policy" calls require authentication.
AttestationAdministrationClient client = attestationBuilder
    .endpoint(endpoint)
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

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

API を getAttestationPolicy 使用して、特定の TEE の現在の構成証明ポリシーを取得します。

String currentPolicy = client.getAttestationPolicy(AttestationType.OPEN_ENCLAVE);
System.out.printf("Current policy for OpenEnclave is: %s\n", currentPolicy);

署名されていない構成証明ポリシーを設定する

構成証明インスタンスが AAD モードの場合、呼び出し元は便利なメソッドを使用して、インスタンスに署名されていない構成証明ポリシーを設定できます。

// Set the listed policy on an attestation instance. Please note that this particular policy will deny all
// attestation requests and should not be used in production.
PolicyResult policyResult = client.setAttestationPolicy(AttestationType.OPEN_ENCLAVE,
    "version=1.0; authorizationrules{=> deny();}; issuancerules{};");
System.out.printf("Policy set for OpenEnclave result: %s\n", policyResult.getPolicyResolution());

署名付き構成証明ポリシーを設定する

分離モード構成証明インスタンスの場合、構成証明インスタンスで構成証明署名証明書に関連付けられているキーを使用して、設定またはリセットポリシー要求に署名する必要があります。

// Set the listed policy on an attestation instance using a signed policy token.
PolicyResult policyResult = client.setAttestationPolicy(AttestationType.SGX_ENCLAVE,
    new AttestationPolicySetOptions()
        .setAttestationPolicy("version=1.0; authorizationrules{=> permit();}; issuancerules{};")
            .setAttestationSigner(new AttestationSigningKey(certificate, privateKey)));
System.out.printf("Policy set for Sgx result: %s\n", policyResult.getPolicyResolution());

ポリシー管理証明書を一覧表示する

構成証明インスタンスがモードの Isolated 場合、ポリシー API には追加の承認証明が必要です。この証明は、セットポリシー API とリセットポリシー API に渡されるパラメーターを介して AttestationSigningKey 提供されます。

各 Isolated モードインスタンスには証明書のセットがあり、呼び出し元が構成証明ポリシーを設定する権限を持っているかどうかを判断します。構成証明ポリシーが設定されると、クライアントはサービスに署名された "トークン" を提示します。これは、の AttestationSigningKeyキーによって署名されます。の証明書 AttestationSigningKey を含む署名済みトークンは構成証明サービスに送信され、トークンがトークンの公開キーに対応する秘密キーで署名されたことを確認します。ポリシーの設定またはリセット操作は、トークン内の証明書がポリシー管理トークンの 1 つである場合にのみ成功します。この操作により、クライアントがポリシー管理証明書の 1 つに関連付けられている秘密キーを所有しているため、操作の実行が許可されます。

AttestationSignerCollection signers = client.listPolicyManagementCertificates();
System.out.printf("Instance %s contains %d signers.\n", endpoint, signers.getAttestationSigners().size());
for (AttestationSigner signer : signers.getAttestationSigners()) {
    System.out.printf("Certificate Subject: %s", signer.getCertificates().get(0).getSubjectDN().toString());
}

ポリシー管理証明書を追加する

ポリシー管理証明書のセットに新しい証明書を追加します。ポリシー管理証明書を追加する要求は、既存のポリシー管理証明書の 1 つに関連付けられている秘密キーで署名する必要があります (これにより、呼び出し元がポリシー証明書のセットを更新する権限が付与されます)。

注: 同じ証明書を 2 回追加してもエラーとは見なされません。証明書が既に存在する場合、追加は無視されます (再試行によって追加が複数回実行される可能性があるため、驚くべき動作が発生する可能性があります)。

System.out.printf("Adding new certificate %s\n", certificateToAdd.getSubjectDN().toString());
PolicyCertificatesModificationResult modificationResult = client.addPolicyManagementCertificate(
    new PolicyManagementCertificateOptions(certificateToAdd,
        new AttestationSigningKey(isolatedCertificate, isolatedKey)));
System.out.printf("Updated policy certificate, certificate add result: %s\n",
    modificationResult.getCertificateResolution());
System.out.printf("Added certificate thumbprint: %s\n", modificationResult.getCertificateThumbprint());

構成証明署名証明書を削除する

ポリシー管理証明書のセットから証明書を削除します。ポリシー管理証明書を削除する要求は、既存のポリシー管理証明書のいずれかに関連付けられている秘密キーを使用して署名する必要があります (これにより、呼び出し元がポリシー証明書のセットを更新する権限が確実に付与されます)。

注: 存在しない証明書を削除してもエラーとは見なされません。証明書が存在しない場合、削除は無視されます (再試行によって削除が複数回実行される可能性があるため、この驚くべき動作が発生する可能性があります)

System.out.printf("Removing existing certificate %s\n", certificateToRemove.getSubjectDN().toString());
PolicyCertificatesModificationResult modificationResult = client.deletePolicyManagementCertificate(
    new PolicyManagementCertificateOptions(certificateToRemove,
        new AttestationSigningKey(isolatedCertificate, isolatedKey)));
System.out.printf("Updated policy certificate, certificate remove result: %s\n",
    modificationResult.getCertificateResolution());
System.out.printf("Removed certificate thumbprint: %s\n", modificationResult.getCertificateThumbprint());

トラブルシューティング

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

次の手順

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

共同作成

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

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

このプロジェクトでは、Microsoft オープンソースの倫理規定を採用しています。詳細については、「倫理規定の FAQ」をご覧ください。追加の質問やコメントがある場合は opencode@microsoft.com にお問い合わせください。

インプレッション数

次の方法で共有

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

作業の開始

パッケージを組み込む

BOM ファイルを含める

直接依存関係を含める

前提条件

クライアントを認証する

主要な概念

構成証明

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

ポリシー管理

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

例

同期構成証明クライアントをインスタンス化する

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

SGX エンクレーブを構成証明する

同期管理クライアントをインスタンス化する

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

署名されていない構成証明ポリシーを設定する

署名付き構成証明ポリシーを設定する

ポリシー管理証明書を一覧表示する

ポリシー管理証明書を追加する

構成証明署名証明書を削除する

トラブルシューティング

次の手順

共同作成

フィードバック

その他のリソース

次の方法で共有

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

作業の開始

パッケージを組み込む

BOM ファイルを含める

直接依存関係を含める

前提条件

クライアントを認証する

主要な概念

構成証明

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

ポリシー管理

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

例

同期構成証明クライアントをインスタンス化する

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

SGX エンクレーブを構成証明する

同期管理クライアントをインスタンス化する

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

署名されていない構成証明ポリシーを設定する

署名付き構成証明ポリシーを設定する

ポリシー管理証明書を一覧表示する

ポリシー管理証明書を追加する

構成証明署名証明書を削除する

トラブルシューティング

次の手順

共同作成

フィードバック

その他のリソース

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