Azure Attestation Clientbibliothek für .NET – 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 TPM-basierten (Trusted Platform Module) Plattformen sowie den Nachweis des Zustands vertrauenswürdiger Ausführungsumgebungen (Trusted Execution Environments, TEEs), wozu beispielsweise SGX-Enclaves (Intel® Software Guard Extensions) und VBS-Enclaves (virtualisierungsbasierte Sicherheit) zählen.

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

HINWEIS: Dies ist ein Vorschau-SDK für den Microsoft Azure Attestation-Dienst. Es bietet alle wichtigen Funktionen für den Zugriff auf den Azure Attestation-Dienst. Er sollte als "unverändert" betrachtet werden und unterliegt in Zukunft Änderungen, die die Kompatibilität mit früheren Versionen beeinträchtigen können.

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

Erste Schritte

Voraussetzungen

• Ein Azure-Abonnement. Für die Verwendung von Azure-Diensten, einschließlich des Microsoft 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 beim Erstellen eines Kontos nutzen.
• Eine vorhandene Azure Attestation-Instanz oder Sie können den in jeder Azure-Region verfügbaren "freigegebenen Anbieter" verwenden. Wenn Sie einen Azure Attestation Dienst instance erstellen müssen, können Sie das Azure-Portal oder die Azure CLI verwenden.

Installieren des Pakets

Installieren Sie die Microsoft Azure Attestation-Clientbibliothek für .NET mit NuGet:

dotnet add package Azure.Security.Attestation --prerelease

Authentifizieren des Clients

Um mit dem Microsoft Azure Attestation-Dienst interagieren zu können, müssen Sie eine instance der Nachweisclient- oder Nachweisverwaltungsclientklasse erstellen. Sie benötigen einen Nachweis instance URL, die möglicherweise als "DNS-Name" im Portal angezeigt wird, und die Anmeldeinformationen des geheimen Clientschlüssels (Client-ID, Geheimer Clientschlüssel, Mandanten-ID), um ein Clientobjekt instanziieren zu können.

Die Authentifizierung geheimer Clientschlüsselanmeldeinformationen wird in diesem Abschnitt mit den ersten Schritten verwendet, aber Sie finden weitere Möglichkeiten zur Authentifizierung mit der Azure-Identität. Um den unten gezeigten Anbieter DefaultAzureCredential oder andere Anbieter von Anmeldeinformationen zu verwenden, die mit dem Azure SDK bereitgestellt werden, sollten Sie das Azure.Identity-Paket installieren:

dotnet add package 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 dessen 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 Dienstprinzipalobjekt-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 (Mandanten) 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 Nachweisrichtlinienverwaltung (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 über seine Authentifizierungsanmeldeinformationen hinaus bereitstellen, um zu überprüfen, ob er autorisiert ist, den Status eines Nachweises instance zu ändern.

Schließlich unterstützt jede Region, in der der Microsoft Azure Attestation-Dienst verfügbar ist, eine "freigegebene" instance, die verwendet werden kann, um SGX-Enklaven zu bestätigen, die nur mit der Azure-Baseline überprüft werden müssen (es gibt keine Richtlinien, die auf die freigegebene instance angewendet werden). Der TPM-Nachweis ist im freigegebenen instance nicht verfügbar. Die freigegebene instance erfordert zwar die AAD-Authentifizierung, verfügt jedoch über keine RBAC-Richtlinien. Jeder Kunde mit einem gültigen AAD-Bearertoken kann die Verwendung des freigegebenen instance 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 erfüllt, die auf diese Umgebung angewendet werden.

Ermittlung und Überprüfung des Zertifikats für das Signieren des Zertifikats des Nachweisdiensttokens

Eine der kernbetriebsbezogenen Garantien des Azure Attestation Service ist, dass der Dienst "operativ außerhalb des TCB" ausgeführt wird. Mit anderen Worten, 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 zu gewährleisten, 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 Enklave des Nachweisdiensts befindet.

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

Wenn der MAA-Dienst instance 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.

Das AttestationResponse -Objekt enthält zwei Standard Eigenschaften: Token und Value. Die Token -Eigenschaft enthält das vollständige Token, das vom Nachweisdienst zurückgegeben wird, und die Value -Eigenschaft enthält den Text der JSON-Webtokenantwort.

Richtlinienverwaltung

Für jeden Nachweisdienst instance wird eine Richtlinie angewendet, die zusätzliche Kriterien definiert, die der Kunde definiert hat.

Weitere Informationen zu Nachweisrichtlinien finden Sie unter Nachweisrichtlinie.

Zertifikatverwaltung der Richtlinienverwaltung

Wenn ein Nachweis instance im Modus "Isoliert" ausgeführt wird, hat der Kunde, der die instance erstellt hat, zum Zeitpunkt der Erstellung des instance ein Richtlinienverwaltungszertifikat bereitgestellt. Für alle Richtlinienänderungsvorgänge muss der Kunde die Richtliniendaten mit einem der vorhandenen Richtlinienverwaltungszertifikate signieren. Mit den Zertifikatverwaltungs-APIs für die Richtlinienverwaltung können Clients die Zertifikate für die Richtlinienverwaltung "rollieren".

Isolierter Modus und AAD-Modus

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

AttestationType

Der Microsoft Azure Attestation-Dienst unterstützt je nach Umgebung den Nachweis verschiedener Arten von Beweisen. 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-API oe_get_reportoe_get_evidence gesammelt wurde.
• SgxEnclave: Ein Intel(tm) Prozessor, der Code in einer SGX-Enclave ausführt, bei dem der Nachweisnachweis mithilfe des 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 Inittimedaten

RuntimeData bezieht sich auf Daten, die der Logik der Intel SGX-Quote-Generierung oder den oe_get_report/oe_get_evidence APIs angezeigt werden. Der Azure Attestation-Dienst überprüft, ob die ersten 32 Bytes des report_data Felds im SGX-Quote/OE-Bericht/OE-Nachweis mit dem SHA256-Hash der RuntimeData übereinstimmen.

InitTime-Daten beziehen sich auf Daten, die zum Konfigurieren der nachweisbaren SGX-Enclave verwendet werden.

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

Threadsicherheit

Wir garantieren, dass alle Client-instance Methoden threadsicher und unabhängig voneinander sind (Richtlinie). Dadurch wird sichergestellt, dass die Empfehlung, Clientinstanzen wiederzuverwenden, immer sicher ist, auch threadsübergreifend.

Zusätzliche Konzepte

Clientoptionen | Zugreifen auf die Antwort | Vorgänge | mit langer AusführungsdauerBehandeln von Fehlern | Diagnose | Spott | Clientlebensdauer

Beispiele

• Erstellen eines Nachweisclients instance
• Nachweis einer SGX-Enklave
• Abrufen der Nachweisrichtlinie
• Abrufen von Tokenvalidierungszertifikaten
• Erstellen eines Nachweisclients instance

Erstellen von Client-instance

Erstellt eine instance des Nachweisclients unter uri endpoint.

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

Abrufen der Nachweisrichtlinie

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

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

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

Festlegen einer Nachweisrichtlinie für einen angegebenen Nachweistyp

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

Unter den Abdeckungen erstellen die SetPolicy-APIs ein JSON-Webtoken auf Der Grundlage des Richtliniendokuments und der Signaturinformationen, die an den Nachweisdienst gesendet werden.

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));

Clients müssen überprüfen können, ob das Dokument der Nachweisrichtlinie nicht geändert wurde, bevor das Richtliniendokument von der Enklave 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:

• PolicySigner - wenn der SetPolicy Aufruf ein Signaturzertifikat enthält, ist dies das Zertifikat, das zum Zeitpunkt des Aufrufs SetPolicy bereitgestellt wurde. Wenn kein Richtlinien signierer festgelegt wurde, ist dies NULL.
• PolicyTokenHash – dies ist der Hash des JSON-Webtokens , das an den Dienst gesendet wird.

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

// 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()));

Nachweis der SGX-Enclave

Verwenden Sie die AttestSgxEnclave -Methode, um eine SGX-Enklave zu bestätigen.

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

Eine Lösung für dieses Problem ist das sogenannte "Secure Key Release", ein Muster, das diese Art der 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" der dritten Seite senden. Die vertrauende Seite überprüft dann, ob das Nachweistoken vom Nachweisdienst erstellt wurde, und so 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, um ein Einer Anforderung zugeordnetes Nachweistoken abzurufen.

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 (binaryQuote) aus der SGX-Enklave generiert haben, die Sie nachweisen, und "Laufzeitdaten" (runtimeData), auf die im SGX-Angebot verwiesen wird.

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

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

Abrufen von Tokenzertifikaten

Verwenden Sie GetSigningCertificatesAsync zum Abrufen der Zertifikate, die zum Überprüfen des vom Nachweisdienst zurückgegebenen Tokens verwendet werden können.

var client = GetAttestationClient();

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

Problembehandlung

Die meisten Vorgänge des Nachweisdiensts lösen eine RequestFailedException bei Einem Fehler mit hilfreichen ErrorCodes aus. Viele dieser Fehler können wiederhergestellt werden.

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

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 zur Lizenzvereinbarung 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.

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