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

このパッケージは Python 2.7、3.6 から 3.9 でテストされています。

Azure ライブラリの詳細については、 Azure SDK for Python のリリースページを参照してください。

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

作業の開始

前提条件

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

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

PyPI を使用して Python 用Azure Attestation クライアントライブラリをインストールします。

pip install azure-security-attestation

クライアントを認証する

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

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

pip install azure-identity

資格情報の作成/取得

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

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

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

Output:

{
    "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

Output:

"<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" モードで実行されている場合、顧客は認証資格情報以外の追加情報を提供して、構成証明インスタンスの状態を変更する権限があることを確認する必要があります。

最後に、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 を使用してサーバーによって発行された証明書を検証できます。

ポリシー管理

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

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

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

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

分離モードと AAD モード

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

AttestationType

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 シリーズの仮想マシンではサポートされていないことに注意してください。

その他の概念

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

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

attest_client = AttestationClient(
    endpoint=base_uri,
    credential=DefaultAzureCredential())

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

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

policy, token = attest_client.get_policy(AttestationType.SGX_ENCLAVE)
print('Instance SGX policy: ', policy)
print('Token: ', token)

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

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

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

policy_set_response = attest_client.set_policy(AttestationType.SGX_ENCLAVE,
    attestation_policy,
    signing_key=key,
    signing_certificate=signing_certificate)
new_policy, _ = attest_client.get_policy(AttestationType.SGX_ENCLAVE)
# `new_policy` will equal `attestation_policy`.

サービスインスタンスが AAD モードで実行されている場合は、set_policyの呼び出しを簡略化できます。

policy_set_response = attest_client.set_policy(AttestationType.SGX_ENCLAVE,            
    attestation_policy)
# Now retrieve the policy which was just set.
new_policy, _ = attest_client.get_policy(AttestationType.SGX_ENCLAVE)

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

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

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

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

from cryptography.hazmat.primitives import hashes

expected_policy = AttestationPolicyToken(
    attestation_policy,
    signing_key=key,
    signing_certificate=signing_certificate)
hasher = hashes.Hash(hashes.SHA256())
hasher.update(expected_policy.serialize().encode('utf-8'))
expected_hash = hasher.finalize()

# `expected_hash` will exactly match `policy_set_response.policy_token_hash`

Attest SGX エンクレーブ

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

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

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

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

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

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

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

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

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

response, token = attest_client.attest_sgx_enclave(quote, runtime_data=runtime_data)

この時点で、attestationResult のenclave_held_data属性は、入力バイナリ runtime_dataを保持します。

トークンが "証明書利用者" に渡されるようになりました。証明書利用者は、トークンが構成証明サービスによって発行されたことを検証します。次に、EnclaveHeldData フィールドから非対称キーを抽出します。証明書利用者は、非対称キーを使用してその "キー" データを暗号化し、エンクレーブに送信します。

encrypted_data = send_token_to_relying_party(attestationResult.Token)

暗号化されたデータをエンクレーブに渡し、そのデータを復号化できるようになりました。

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

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

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

signers = attest_client.get_signing_certificates()
for signer in signers:
    from cryptography.hazmat.backends import default_backend
    cert = cryptography.x509.load_pem_x509_certificate(signer.certificates[0].encode('ascii'), backend=default_backend())
    print('Cert  iss:', cert.issuer, '; subject:', cert.subject)

トラブルシューティング

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

try:
    response, _ = attest_client.attest_sgx_enclave(
        quote,
        runtime_data=AttestationData(runtime_data, is_json=False))
except HttpResponseError as ex:
    # Ignore invalid quote errors.
    if ex.error == "InvalidParameter":
        pass
}

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

次のステップ

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

共同作成

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

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

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

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

フィードバックの提供

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

インプレッション数

次の方法で共有

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

作業の開始

前提条件

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

クライアントを認証する

資格情報の作成/取得

主要な概念

構成証明

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

ポリシー管理

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

分離モードと AAD モード

AttestationType

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

その他の概念

例

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

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

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

Attest SGX エンクレーブ

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

トラブルシューティング

次のステップ

共同作成

フィードバックの提供

その他のリソース

次の方法で共有

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

作業の開始

前提条件

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

クライアントを認証する

資格情報の作成/取得

主要な概念

構成証明

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

ポリシー管理

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

分離モードと AAD モード

AttestationType

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

その他の概念

例

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

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

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

Attest SGX エンクレーブ

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

トラブルシューティング

次のステップ

共同作成

フィードバックの提供

その他のリソース

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

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

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

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