Azure Attestation Clientbibliothek für Python– Version 1.0.0

Der Microsoft Azure Attestation-Dienst (MAA) ist eine einheitliche Lösung zum Remote-Überprüfen der Vertrauenswürdigkeit einer Plattform und der Integrität der darin ausgeführten Binärdateien. Der Dienst unterstützt den Nachweis der Plattformen, die von Trusted Platform Modules (TPMs) unterstützt werden, sowie die Möglichkeit, den Status von vertrauenswürdigen Ausführungsumgebungen (Trusted Execution Environments, TEEs) wie Intel(tm) Software Guard Extensions (SGX)-Enclaves und virtualisierungsbasierten Sicherheits-Enclaves (VBS) zu bestätigen.

Der Nachweis ist ein Prozess, um zu veranschaulichen, dass Softwarebinärdateien auf einer vertrauenswürdigen Plattform ordnungsgemäß instanziiert wurden. Vertrauende Remoteseiten können dann sicher sein, dass nur die vorgesehene Software auf vertrauenswürdiger Hardware ausgeführt wird. Azure Attestation ist ein einheitlicher Service für die Kunden und ein Framework für den Nachweis.

Azure Attestation ermöglicht innovative Sicherheitsparadigmen wie Confidential Computing unter Azure und Intelligent Edge-Schutz. Kunden haben die Möglichkeit angefordert, den Standort eines Computers, die Stellung eines virtuellen Computers (VM) auf diesem Computer und die Umgebung, in der die Enclaves auf diesem virtuellen Computer ausgeführt werden, einzeln zu überprüfen. Azure Attestation ermöglicht diese und viele zusätzliche Kundenanforderungen.

Azure Attestation erhält Beweise von Compute-Entitäten, wandelt sie in einen Satz von Ansprüchen um, überprüft sie anhand konfigurierbarer Richtlinien und erzeugt kryptografische Nachweise für anspruchsbasierte Anwendungen (z. B. vertrauende Seiten und Überwachungsbehörden).

Dieses Paket wurde mit Python 2.7, 3.6 bis 3.9 getestet.

Eine vollständigere Ansicht der Azure-Bibliotheken finden Sie auf der Releaseseite des Azure SDK für Python.

Quellcode | Paket (PyPI) | API-Referenzdokumentation | Produktdokumentation

Erste Schritte

Voraussetzungen

• Ein Azure-Abonnement. Um Azure-Dienste verwenden zu können, einschließlich des Azure Attestation-Diensts, benötigen Sie ein Abonnement. Wenn Sie nicht über ein vorhandenes Azure-Konto verfügen, können Sie sich für eine kostenlose Testversion registrieren oder Ihre Visual Studio-Abonnementvorteile nutzen, wenn Sie ein Konto erstellen.
• Eine vorhandene Azure Attestation-Instanz oder Sie können den in jeder Azure-Region verfügbaren "freigegebenen Anbieter" verwenden. Wenn Sie eine Azure Attestation Dienstinstanz erstellen müssen, können Sie das Azure-Portal oder die Azure CLI verwenden.

Installieren des Pakets

Installieren Sie die Azure Attestation-Clientbibliothek für Python mit PyPI:

pip install azure-security-attestation

Authentifizieren des Clients

Um mit dem Azure Attestation-Dienst zu interagieren, müssen Sie eine Instanz der Attestation Client- oder Attestation Administration Client-Klasse erstellen. Sie benötigen einen Nachweisendpunkt, den Sie im Portal möglicherweise als "Nachweis-URI" sehen, und Clientanmeldeinformationen (Client-ID, geheimer Clientschlüssel, Mandanten-ID), um ein Clientobjekt zu instanziieren.

Die Authentifizierung von Anmeldeinformationen für geheime Clientschlüssel wird in diesem Abschnitt zu den ersten Schritten verwendet, aber Sie finden weitere Möglichkeiten zur Authentifizierung mit dem Azure-Identitätspaket. Um den unten gezeigten DefaultAzureCredential-Anbieter oder andere Mit dem Azure SDK bereitgestellte Anmeldeinformationsanbieter zu verwenden, sollten Sie das Paket azure-identity installieren:

pip install azure-identity

Erstellen/Abrufen von Anmeldeinformationen

Verwenden Sie den folgenden Azure CLI-Codeausschnitt , um Anmeldeinformationen für geheime Clientschlüssel zu erstellen/abzurufen.

• Erstellen Sie einen Dienstprinzipal, und konfigurieren Sie den Zugriff auf Azure-Ressourcen:

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

  Ausgabe:

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

• Notieren Sie sich die Dienstprinzipal-Objekt-ID.

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

  Ausgabe:

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

• Verwenden Sie die oben zurückgegebenen Anmeldeinformationen, um AZURE_CLIENT_ID (appId), AZURE_CLIENT_SECRET (Kennwort) und AZURE_TENANT_ID Umgebungsvariablen (Mandant) festzulegen. Das folgende Beispiel zeigt eine Möglichkeit, dies in PowerShell zu tun:

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

Weitere Informationen zu den Azure Identity-APIs und deren Verwendung finden Sie unter Azure Identity-Clientbibliothek.

Wichtige Begriffe

Dieses Vorschau-SDK bietet vier Hauptfunktionen:

• SGX- und TPM-Enclave-Nachweis.
• MAA-Nachweistoken: Signaturzertifikatermittlung und -validierung.
• Verwaltung von Nachweisrichtlinien.
• Zertifikatverwaltung für Nachweisrichtlinien (ja, Richtlinienverwaltung).

Der Microsoft Azure Attestation-Dienst wird in zwei separaten Modi ausgeführt: "Isoliert" und "AAD". Wenn der Dienst im Modus "Isoliert" ausgeführt wird, muss der Kunde zusätzliche Informationen bereitstellen, die über seine Authentifizierungsanmeldeinformationen hinausgehen, um zu überprüfen, ob er berechtigt ist, den Status einer Nachweisinstanz zu ändern.

Schließlich unterstützt jede Region, in der der Azure Attestation Dienst verfügbar ist, eine "freigegebene" Instanz, die zum Nachweis von SGX-Enclaves verwendet werden kann, die nur anhand der Azure-Baseline überprüft werden müssen (es gibt keine Richtlinien, die auf die freigegebene Instanz angewendet werden). Der TPM-Nachweis ist in der freigegebenen Instanz nicht verfügbar. Obwohl die freigegebene Instanz AAD-Authentifizierung erfordert, verfügt sie über keine RBAC-Richtlinien. Jeder Kunde mit einem gültigen AAD-Bearertoken kann die Verwendung der freigegebenen Instanz nachweisen.

Nachweis

SGX- oder TPM-Nachweis ist der Prozess der Überprüfung von Beweisen, die aus einer vertrauenswürdigen Ausführungsumgebung gesammelt wurden, um sicherzustellen, dass sie sowohl die Azure-Baseline für diese Umgebung als auch kundendefinierte Richtlinien für diese Umgebung erfüllt.

Ermittlung und Überprüfung des Zertifikats für die Signatur des Nachweisdiensttokens

Eine der kernbetriebsbezogenen Garantien des Azure Attestation Service ist, dass der Dienst "operativ außerhalb des TCB" ausgeführt wird. Anders ausgedrückt: Es gibt keine Möglichkeit, dass ein Microsoft-Operator den Betrieb des Diensts manipulieren oder vom Client gesendete Daten beschädigen könnte. Um diese Garantie sicherzustellen, wird der Kern des Nachweisdiensts in einer Intel(tm) SGX-Enclave ausgeführt.

Damit Kunden überprüfen können, ob Vorgänge tatsächlich innerhalb der Enclave ausgeführt wurden, werden die meisten Antworten des Nachweisdiensts in einem JSON-Webtoken codiert, das von einem Schlüssel signiert wird, der sich in der Enclave des Nachweisdiensts befindet.

Dieses Token wird von einem Signaturzertifikat signiert, das vom MAA-Dienst für die angegebene Instanz ausgestellt wurde.

Wenn die MAA-Dienstinstanz in einer Region ausgeführt wird, in der der Dienst in einer SGX-Enclave ausgeführt wird, kann das vom Server ausgestellte Zertifikat mithilfe der oe_verify_attestation_certificate-API überprüft werden.

Richtlinienverwaltung

Auf jede Nachweisdienstinstanz wird eine Richtlinie angewendet, die zusätzliche Kriterien definiert, die der Kunde definiert hat.

Weitere Informationen zu Nachweisrichtlinien finden Sie unter Nachweisrichtlinie.

Verwaltung von Richtlinienverwaltungszertifikaten

Wenn eine Nachweisinstanz im Modus "Isoliert" ausgeführt wird, hat der Kunde, der die Instanz erstellt hat, zum Zeitpunkt der Erstellung der Instanz ein Richtlinienverwaltungszertifikat bereitgestellt. Alle Richtlinienänderungsvorgänge erfordern, dass der Kunde die Richtliniendaten mit einem der vorhandenen Richtlinienverwaltungszertifikate signiert. Mit den Zertifikatverwaltungs-APIs für die Richtlinienverwaltung können Clients die Richtlinienverwaltungszertifikate "rollieren".

Isolierter Modus und AAD-Modus

Jede Microsoft Azure Attestation-Dienstinstanz wird entweder im Modus "AAD" oder "Isoliert" ausgeführt. Wenn eine MAA-Instanz im AAD-Modus ausgeführt wird, bedeutet dies, dass der Kunde, der die Nachweisinstanz erstellt hat, azure Active Directory- und Azure Role Based Access Control-Richtlinien ermöglicht, den Zugriff auf die Nachweisinstanz zu überprüfen.

AttestationType

Der Azure Attestation-Dienst unterstützt den Nachweis verschiedener Arten von Beweisen abhängig von der Umgebung. Derzeit unterstützt MAA die folgenden Umgebungen für vertrauenswürdige Ausführung:

• OpenEnclave: Ein Intel(tm)-Prozessor, der Code in einer SGX-Enclave ausführt, bei dem der Nachweisnachweis mithilfe der OpenEnclave-oe_get_report- oder oe_get_evidence-API gesammelt wurde.
• SgxEnclave: Ein Intel(tm)-Prozessor, der Code in einer SGX-Enclave ausführt, bei dem der Nachweis mit dem Intel SGX SDK gesammelt wurde.
• Tpm: Eine virtualisierungsbasierte Sicherheitsumgebung, in der das Trusted Platform-Modul des Prozessors verwendet wird, um den Nachweis zu erbringen.

Laufzeitdaten und Inittime-Daten

RuntimeData bezieht sich auf Daten, die der Logik der Intel SGX-Quote-Generierung oder den oe_get_report/oe_get_evidence APIs angezeigt werden. Wenn der Aufrufer der Nachweis-API ein runtime_data Attribut bereitgestellt hat, überprüft der Azure Attestation Dienst, ob die ersten 32 Byte des report_data Felds im SGX-Zitat/OE-Bericht/OE-Nachweis mit dem SHA256-Hash von runtime_dataübereinstimmen.

InitTime-Daten beziehen sich auf Daten, die zum Konfigurieren der zu bestätigenden SGX-Enclave verwendet werden.

Beachten Sie, dass InitTime-Daten auf virtuellen Computern der Azure DCsv2-Serie nicht unterstützt werden.

Zusätzliche Konzepte

Beispiele

• Erstellen einer Nachweisclientinstanz
• Nachweis einer SGX-Enclave
• Abrufen der Nachweisrichtlinie
• Abrufen von Tokenvalidierungszertifikaten
• Erstellen einer Nachweisclientinstanz

Erstellen einer Clientinstanz

Erstellt eine Instanz des Nachweisclients unter URI endpoint.

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

Abrufen der Nachweisrichtlinie

Die set_policy -Methode ruft die Nachweisrichtlinie aus dem Dienst ab. Nachweisrichtlinien werden pro Nachweistyp instanziert. Der AttestationType Parameter definiert den abzurufenden Typ.

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

Festlegen einer Nachweisrichtlinie für einen angegebenen Nachweistyp

Wenn die Nachweisdienstinstanz im isolierten Modus ausgeführt wird, muss die set_policy-API ein Signaturzertifikat (und einen privaten Schlüssel) bereitstellen, mit dem überprüft werden kann, ob der Aufrufer berechtigt ist, die Richtlinie für die Nachweisinstanz zu ändern. Wenn die Dienstinstanz im AAD-Modus ausgeführt wird, sind das Signaturzertifikat und der Schlüssel optional.

Im Cover erstellen die SetPolicy-APIs ein JSON-Webtoken basierend auf dem Richtliniendokument und den Signaturinformationen, die an den Nachweisdienst gesendet werden.

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`.

Wenn die Dienstinstanz im AAD-Modus ausgeführt wird, kann der Aufruf von set_policy vereinfacht werden:

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)

Clients müssen überprüfen können, ob das Dokument der Nachweisrichtlinie nicht geändert wurde, bevor das Richtliniendokument von der Enclave des Nachweisdiensts empfangen wurde.

Im PolicyResult werden zwei Eigenschaften bereitgestellt, die verwendet werden können, um zu überprüfen, ob der Dienst das Richtliniendokument empfangen hat:

• policy_signer : Wenn der set_policy Anruf ein Signaturzertifikat enthält, ist dies das Zertifikat, das zum Zeitpunkt des Aufrufs set_policy bereitgestellt wurde. Wenn kein Richtlinien signierer festgelegt wurde, ist dies NULL.
• policy_token_hash : Dies ist der Hash des JSON-Webtokens , das an den Dienst gesendet wird.

Um den Hash zu überprüfen, können Clients ein Nachweisrichtlinientoken generieren und den aus diesem Token generierten Hash überprüfen:

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`

Nachweis von SGX Enclave

Verwenden Sie die attest_sgx_enclave-Methode , um eine SGX-Enclave zu bestätigen.

Eine der wichtigsten Herausforderungen, die Kunden bei der Interaktion mit verschlüsselten Umgebungen haben, besteht darin, sicherzustellen, dass Sie sicher mit dem code kommunizieren können, der in der Umgebung ausgeführt wird ("Enclave-Code").

Eine Lösung für dieses Problem ist das sogenannte "Secure Key Release", ein Muster, das eine sichere Kommunikation mit Enclave-Code ermöglicht.

Um das Muster "Secure Key Release" zu implementieren, generiert der Enclavecode einen kurzlebigen asymmetrischen Schlüssel. Anschließend wird der öffentliche Teil des Schlüssels in ein Format serialisiert (möglicherweise ein JSON-Webschlüssel oder PEM oder ein anderes Serialisierungsformat).

Der Enclavecode berechnet dann den SHA256-Wert des öffentlichen Schlüssels und übergibt ihn als Eingabe an Code, der ein SGX-Zitat generiert (für OpenEnclave wäre dies der oe_get_evidence oder oe_get_report).

Der Client sendet dann das SGX-Angebot und den serialisierten Schlüssel an den Nachweisdienst. Der Nachweisdienst überprüft das Angebot und stellt sicher, dass der Hash des Schlüssels im Anführungszeichen vorhanden ist, und stellt ein "Nachweistoken" aus.

Der Client kann dann dieses Nachweistoken (das den serialisierten Schlüssel enthält) an eine "vertrauende Seite" eines Drittanbieters senden. Die vertrauende Seite überprüft dann, ob das Nachweistoken vom Nachweisdienst erstellt wurde. Daher kann der serialisierte Schlüssel verwendet werden, um einige Daten zu verschlüsseln, die von der "vertrauenden Seite" gespeichert sind, um sie an den Dienst zu senden.

Dieses Beispiel zeigt ein gängiges Muster des Aufrufens des Nachweisdiensts zum Abrufen eines Nachweistokens, das einer Anforderung zugeordnet ist.

In diesem Beispiel wird davon ausgegangen, dass Sie über ein vorhandenes AttestationClient -Objekt verfügen, das mit dem Basis-URI für Ihren Endpunkt konfiguriert ist. Es wird auch davon ausgegangen, dass Sie ein SGX-Angebot (quote) aus der SGX-Enclave generiert haben, die Sie nachweisen, und "Laufzeitdaten" (runtime_data), auf die im SGX-Angebot verwiesen wird.

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

An diesem Punkt enthält das attribut enclave_held_data im attestationResult die eingabebinär runtime_data.

Das Token wird nun an die "vertrauende Seite" übergeben. Die vertrauende Seite überprüft, ob das Token vom Nachweisdienst ausgestellt wurde. Anschließend wird der asymmetrische Schlüssel aus dem Feld EnclaveHeldData extrahiert. Die vertrauende Seite verschlüsselt dann ihre "Schlüssel"-Daten mithilfe des asymmetrischen Schlüssels und überträgt sie zurück an die Enclave.

encrypted_data = send_token_to_relying_party(attestationResult.Token)

Jetzt können die verschlüsselten Daten an die Enclave übergeben werden, die diese Daten entschlüsseln kann.

Weitere Informationen zum Durchführen der Überprüfung von Nachweistoken finden Sie im MAA-Dienstnachweisbeispiel.

Abrufen von Tokenzertifikaten

Verwenden Sie get_signing_certificates , um die Zertifikate abzurufen, die zum Überprüfen des vom Nachweisdienst zurückgegebenen Tokens verwendet werden können.

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)

Problembehandlung

Die meisten Nachweisdienstvorgänge lösen ausnahmen aus, die in Azure Core definiert sind. Die Nachweisdienst-APIs lösen bei Einem Fehler einen HttpResponseError mit hilfreichen Fehlercodes aus. Viele dieser Fehler können wiederhergestellt werden.

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
}

Weitere Informationen zur Problembehandlung für den MAA-Dienst finden Sie hier.

Nächste Schritte

Weitere Informationen zum Microsoft Azure Attestation-Dienst finden Sie auf unserer Dokumentationsseite.

Mitwirken

Beiträge und Vorschläge für dieses Projekt sind willkommen. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. Weitere Informationen finden Sie auf der Website lizenzvertrag für Mitwirkende.

Wenn Sie einen Pull Request (PR) übermitteln, überprüft ein CLA-Bot automatisch, ob Sie eine Lizenzvereinbarung bereitstellen und den PR entsprechend ergänzen müssen (z.B. mit einer Bezeichnung oder einem Kommentar). Führen Sie einfach die Anweisungen des Bots aus. Sie müssen dies nur einmal für alle Repositorys ausführen, die unsere CLA verwenden.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.

Ausführliche Informationen zum Erstellen, Testen und Mitwirken zu diesen Bibliotheken finden Sie unter CONTRIBUTING.md .

Feedback geben

Wenn Fehler auftreten oder Vorschläge vorliegen, melden Sie ein Problem im Abschnitt Probleme des Projekts.