Share via

Azure Attestation Clientbibliothek für JavaScript – Version 1.0.0

  • Artikel

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 Trusted Execution Environments (TEEs) wie Intel(tm) Software Guard Extensions (SGX)-Enclaves und virtualisierungsbasierte Sicherheitsenklaven (VBS) zu belegen.

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

Eine vollständigere Ansicht der Azure-Bibliotheken finden Sie in der Typescript-Version des Azure SDK.

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.

Wichtige Links:

Erste Schritte

Die derzeitig unterstützten Umgebungen

Ausführlichere Informationen finden Sie in der Supportrichtlinie.

Voraussetzungen

  • Ein Azure-Abonnement
  • 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 Sie das Paket @azure/attestation.

Installieren Sie die Microsoft Azure Attestation-Clientbibliothek für JavaScript mit NPM:

npm install @azure/attestation

Authentifizieren des Clients

Um mit dem Microsoft Azure Attestation-Dienst interagieren zu können, müssen Sie eine Instanz der Nachweisclient- oder Nachweisverwaltungsclientklasse erstellen. Sie benötigen eine Nachweisinstanz-URL, bei der es sich entweder um den im Portal angezeigten "Nachweis-URI" handelt, oder um einen der gemeinsam genutzten Nachweisanbieter. Sie benötigen auch Clientanmeldeinformationen, um den Nachweisverwaltungsclient zu verwenden oder die attestTpm API aufzurufen. Clientanmeldeinformationen erfordern (Client-ID, geheimer Clientschlüssel, Mandanten-ID), um ein Clientobjekt zu instanziieren.

In diesem Abschnitt mit den ersten Schritten authentifizieren wir uns mithilfe der Anmeldeinformationen des geheimen Clientschlüssels über den DefaultAzureCredential-Anbieter , aber wir bieten weitere Authentifizierungsmechanismen über das @azure/Identitätspaket . So installieren Sie das @azure/identity-Paket

npm 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 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:

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 einer Nachweisinstanz zu ändern.

Schließlich unterstützt jede Region, in der der Microsoft Azure Attestation-Dienst verfügbar ist, eine "freigegebene" Instanz, die verwendet werden kann, um SGX-Enklaven zu bestätigen, die nur mit der Azure-Baseline überprüft werden müssen (es werden keine Richtlinien auf den freigegebenen Anbieter angewendet). Der TPM-Nachweis ist im freigegebenen Anbieter 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 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 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.

Das AttestationResponse -Objekt enthält zwei Hauptattribute: token und value. Das token Attribut enthält das vollständige Token, das vom Nachweisdienst zurückgegeben wird. Das value Attribut enthält den Text der JSON-Webtokenantwort.

Richtlinienverwaltung

Für jede Nachweisdienstinstanz 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 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. 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-Dienstinstanz arbeitet im Modus "AAD" oder "Isoliert". 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-Steuerungsrichtlinien ermöglicht, den Zugriff auf die Nachweisinstanz 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. Wenn der Aufrufer der Nachweis-API ein runtime_data Attribut bereitgestellt hat, überprüft der Azure Attestation-Dienst, ob die ersten 32 Bytes des report_data Felds im SGX-Quote/OE-Bericht/OE-Nachweis mit dem SHA256-Hash von runtime_dataü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.

Zusätzliche Konzepte

Beispiele

Erstellen einer Clientinstanz

Erstellt eine Instanz des Nachweisclients unter Verwendung endpointder Azure-Standardanmeldeinformationen (DefaultAzureCredential).

const credentials = new DefaultAzureCredential();
const client = new AttestationClient(endpoint, {credentials: credentials});

// Retrieve the set of attestation policy signers from the attestation client.
const attestationSigners = await client.getAttestationSigners();

Wenn Sie die attestTpm API nicht aufrufen, müssen Sie keine Anmeldeinformationen für den Zugriff auf den Nachweisclient angeben. Dies bedeutet, dass ein Client einfach mit erstellt werden kann:

const client = new AttestationClient(endpoint);

// Retrieve the set of attestation policy signers from the attestation client.
const attestationSigners = await client.getAttestationSigners();

Erstellt eine Instanz des Nachweisverwaltungsclients unter uri endpoint.

Beachten Sie, dass für den Verwaltungsclient Azure-Anmeldeinformationen erforderlich sind .

  const client = new AttestationAdministrationClient(endpoint, new DefaultAzureCredential());

  // Retrieve the SGX policy from the specified attestation instance.
  const policyResponse = await client.getPolicy(KnownAttestationType.SgxEnclave);

Abrufen der Nachweisrichtlinie

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

const policyResult = await adminClient.getPolicy(attestationType);

// The text policy document is available in the `policyResult.body`
// property.

// The actual attestation token returned by the MAA service is available
// in `policyResult.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 zum Ändern der Richtlinie für die Nachweisinstanz autorisiert ist. Wenn die Dienstinstanz im AAD-Modus ausgeführt wird, sind das Signaturzertifikat und der Schlüssel optional.

Wenn die Dienstinstanz im AAD-Modus ausgeführt wird, erfolgt der Aufruf von setPolicy wie erwartet:

const client = new AttestationAdministrationClient(endpoint, new DefaultAzureCredential());

const newPolicy = `<New Attestation Policy>`;

// Set the new attestation policy. Set the policy as an unsecured policy.
const setPolicyResult = await client.setPolicy(KnownAttestationType.SgxEnclave, newPolicy);

Wenn die Dienstinstanz im isolierten Modus ausgeführt wird, erfordert der Aufruf von setPolicy, dass der Client nachweisen kann, dass er Zugriff auf einen der privaten Schlüssel und Zertifikate der Richtlinienverwaltung hat.

const client = new AttestationAdministrationClient(endpoint, new DefaultAzureCredential());

const newPolicy = `<New Policy Document>`;

// Set the new attestation policy. Set the policy as an secured policy.
const privateKey = <Retrieve isolated mode private key from storage>
const certificate = <Retrieve certificate associated with that private key>

const setPolicyResult = await client.setPolicy(
  KnownAttestationType.OpenEnclave,
  newPolicy,
  {
    privateKey: privateKey,
    certificate: certificate
  }
);

Unter den Abdeckungen erstellen die setPolicy-APIs ein JSON-Webtoken , das im Richtliniendokument certificate enthalten und mit privateKey signiert ist, das dann an den Nachweisdienst gesendet wird.

Wenn ein Client sicherstellen möchte, dass das Dokument der Nachweisrichtlinie nicht geändert wurde, bevor das Richtliniendokument von der Enclave des Nachweisdiensts empfangen wurde, kann er die im PolicyResult-Objct zurückgegebenen Eigenschaften verwenden, um zu überprüfen, ob der Dienst das Richtliniendokument erhalten hat:

  • policySigner - wenn der setPolicy Aufruf einen certificateenthält, ist dieser Wert das zertifikat, das zum Zeitpunkt des setPolicy Aufrufs bereitgestellt wurde. Wenn kein Richtlinien signierer festgelegt wurde, ist dies NULL.
  • policyTokenHash – dies ist der Hash der JSON-Websignatur , die an den Dienst für die setPolicy-API gesendet wird.

Um den Hash zu überprüfen, können Clients ein Nachweisrichtlinientoken (eine Hilfsklasse, die das Token darstellt, das zum Festlegen der Nachweisrichtlinie verwendet wird) erstellen und den aus diesem Token generierten Hash überprüfen:

const expectedPolicy = createAttestationPolicyToken(
  `<Policy Document>`,
  privateKey,
  certificate);

// Use your favorite SHA256 hash generator function to create a hash of the
// stringized JWS.
const expectedHash = generateSha256Hash(expectedPolicy.serialize());

// The hash returned in expectedHash should match the value in
// `setResult.body.policyTokenHash`.

Nachweis von SGX und Open 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 sicher mit dem code kommunizieren können, der in der Umgebung ausgeführt wird ("Enclavecode").

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" 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 Nachweis-URI für Ihren Endpunkt konfiguriert ist. Außerdem wird davon ausgegangen, dass Sie einen OpenEnclave-Bericht (report) aus der SGX-Enclave generiert haben, die Sie nachweisen, und "Laufzeitdaten" (binaryRuntimeData), auf die im SGX-Angebot verwiesen wird.

const attestationResult = await client.attestOpenEnclave(report, {
  runTimeData: binaryRuntimeData
});

Es ist auch möglich, dass das binaryRuntimeData an den Nachweisdienst gesendete als JSON-Daten interpretiert werden soll. In diesem Fall sollte der Client im Aufruf der Nachweis-API folgendes angeben runTimeJson :

const attestationResult = await client.attestOpenEnclave(report, {
  runTimeJson: binaryRuntimeData
});

Wenn Sie das Intel SDK verwenden, um ein "Quote" zu generieren, können Sie das Angebot auf ähnliche Weise überprüfen:

const attestationResult = await client.attestSgxEnclave(quote, {
  runTimeData: binaryRuntimeData
});

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

Abrufen von Tokenzertifikaten

Verwenden Sie getSigningCertificates zum Abrufen der Zertifikate, die zum Überprüfen des vom Nachweisdienst zurückgegebenen Tokens verwendet werden können. Beachten Sie, dass dieser Aufruf einen Client mit Azure-Anmeldeinformationen erstellt, der nicht benötigt wird, wenn Sie die attestSgxEnclave APIs oder attestOpenEnclave aufrufen.

const credentials = new DefaultAzureCredential();
const client = new AttestationClient(endpoint, {credentials: credentials});

const attestationSigners = await client.getAttestationSigners();

console.log(`There are ${attestationSigners.length} signers`);

Problembehandlung

Die meisten Vorgänge des Nachweisdiensts lösen ausnahmen aus, die in Azure Core definiert sind. Die APIs des Nachweisdiensts lösen einen RestError fehler mit hilfreichen Fehlercodes aus. Viele dieser Fehler können wiederhergestellt werden.

try {
  await client.attestSgxEnclave(openEnclaveReport);
} catch (error) {
  console.log(`Exception thrown for invalid request: ${error.message}`);
}

Protokollierung

Die Aktivierung der Protokollierung kann hilfreiche Informationen über Fehler aufdecken. Um ein Protokoll von HTTP-Anforderungen und -Antworten anzuzeigen, legen Sie die Umgebungsvariable AZURE_LOG_LEVEL auf info fest. Alternativ kann die Protokollierung zur Laufzeit aktiviert werden, indem Sie setLogLevel in @azure/logger aufrufen:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Ausführlichere Anweisungen zum Aktivieren von Protokollen finden Sie in der Paketdokumentation zu @azure/logger.

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 .

Feedback geben

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

Aufrufe