Freigeben über

Azure Confidential Ledger REST-Clientbibliothek für JavaScript – Version 1.0.0

  • Artikel

Azure Confidential Ledger bietet einen Dienst für die Protokollierung bei einem unveränderlichen, manipulationssicheren Ledger. Als Teil des Azure Confidential Computing-Portfolios wird Azure Confidential Ledger in SGX-Enklaven ausgeführt. Es basiert auf dem Confidential Consortium Framework von Microsoft Research.

Verwenden Sie diese Bibliothek in hohem Maße auf die Dokumentation des Diensts und unsere Rest-Clientdokumentation.

Wichtige Links:

Erste Schritte

Die derzeitig unterstützten Umgebungen

  • Node.js Version 14.x.x oder höher

Voraussetzungen

  • Ein Azure-Abonnement.
  • Eine ausgeführte Instanz von Azure Confidential Ledger
  • Ein registrierter Benutzer im Confidential Ledger, der normalerweise während der ARM-Ressourcenerstellung zugewiesen wird, mit Administrator Berechtigungen.

Installieren Sie das Paket @azure-rest/confidential-ledger.

Installieren Sie die Azure Condifential Ledger REST-Clientbibliothek für JavaScript mit npm:

npm install @azure-rest/confidential-ledger

Erstellen und Authentifizieren des Clients

Verwenden von Azure Active Directory

In diesem Dokument wird die Verwendung von DefaultAzureCredential zur Authentifizierung beim Confidential Ledger über Azure Active Directory veranschaulicht. Die Umgebungsvariablen finden Sie im Azure-Portal. Akzeptiert jedoch ConfidentialLedger alle @azure-/Identitätsanmeldeinformationen .

DefaultAzureCredential verarbeitet die meisten Azure SDK-Clientszenarien automatisch. Legen Sie zunächst die Werte der Client-ID, der Mandanten-ID und des geheimen Clientschlüssels der AAD-Anwendung als Umgebungsvariablen fest: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET.

Anschließend DefaultAzureCredential kann sich der ConfidentialLedger Client authentifizieren.

Das Erstellen des Clients erfordert auch die URL und ID Ihres Vertraulichen Ledgers, die Sie über die Azure CLI oder das Azure-Portal abrufen können.

Da Confidential Ledgers selbstsignierte Zertifikate verwenden, die sicher generiert und in einer Enclave gespeichert sind, muss das Signaturzertifikat für jedes Confidential Ledger zuerst aus dem Confidential Ledger Identity Service abgerufen werden.

import ConfidentialLedger, { getLedgerIdentity } from "../../src";

const { ledgerIdentityCertificate } = await getLedgerIdentity(
      // for example, test-ledger-name
      LEDGER_IDENTITY,
      // for example, https://identity.confidential-ledger.core.azure.com
      IDENTITY_SERVICE_URL
    );
    const credential = new DefaultAzureCredential();

    // ENDPOINT example: https://test-ledger-name.confidential-ledger.azure.com
    const ledgerClient = ConfidentialLedger(ENDPOINT, ledgerIdentityCertificate, credential);

Verwenden eines Clientzertifikats

Als Alternative zu Azure Active Directory können sich Clients mit einem Clientzertifikat in gegenseitigem TLS anstatt über ein Azure Active Directory-Token authentifizieren. Für diese Art der Authentifizierung muss dem Client eine CertificateCredential übergeben werden, die aus einem Zertifikat und einem privaten Schlüssel besteht, beide im PEM-Format.

import ConfidentialLedger, { getLedgerIdentity } from "@azure-rest/confidential-ledger";

// Get the signing certificate from the Confidential Ledger Identity Service
const { ledgerIdentityCertificate } = await getLedgerIdentity(
      LEDGER_IDENTITY,
      IDENTITY_SERVICE_URL
    );
    // both cert (certificate key) and key (private key) are in PEM format
    const cert = PUBLIC_KEY;
    const key = PRIVATE_KEY;
    // Create the Confidential Ledger Client
    // ENDPOINT example: https://test-ledger-name.confidential-ledger.azure.com
    const ledgerClient = ConfidentialLedger(env.ENDPOINT, ledgerIdentityCertificate, {
      tlsOptions: {
        cert,
        key,
      },
    });

Wichtige Begriffe

Ledgereinträge und Transaktionen

Jeder Schreibvorgang in Azure Confidential Ledger generiert einen unveränderlichen Ledgereintrag im Dienst. Schreibvorgänge, die auch als Transaktionen bezeichnet werden, werden durch Transaktions-IDs eindeutig identifiziert, die mit jedem Schreibvorgang inkrementieren. Nach dem Schreiben können Ledgereinträge jederzeit abgerufen werden.

Receipts

Zustandsänderungen am Confidential Ledger werden in einer Datenstruktur gespeichert, die als Merkle-Struktur bezeichnet wird. Um kryptografisch zu überprüfen, ob Schreibvorgänge ordnungsgemäß gespeichert wurden, kann ein Merkle-Nachweis oder -Beleg für jede Transaktions-ID abgerufen werden.

Sammlungen

Während die meisten Anwendungsfälle ein Ledger umfassen, bieten wir das Sammlungsfeature für den Fall, dass semantisch oder logisch unterschiedliche Datengruppen im selben Vertraulichen Ledger gespeichert werden müssen.

Ledgereinträge werden von ihrem Sammlungsbezeichner abgerufen. Das Confidential Ledger geht immer von einer konstanten, vom Dienst bestimmten Sammlungs-ID für Einträge aus, die ohne Angabe einer Sammlung übermittelt werden.

Benutzer

Benutzer werden direkt mit dem Confidential Ledger anstatt über Azure verwaltet. Benutzer können AAD-basiert sein, durch ihre AAD-Objekt-ID oder zertifikatbasiert durch ihren PEM-Zertifikatfingerabdruck identifiziert sein.

Confidential Computing

Mit Azure Confidential Computing können Sie Ihre Daten isolieren und schützen, während sie in der Cloud verarbeitet werden. Azure Confidential Ledger wird auf virtuellen Azure Confidential Computing-Computern ausgeführt und bietet somit einen besseren Schutz der Daten durch Verschlüsselung der verwendeten Daten.

Vertrauliches Konsortiumsframework

Azure Confidential Ledger basiert auf dem Open-Source Confidential Consortium Framework (CCF) von Microsoft Research. Unter CCF werden Anwendungen von einem Konsortium von Mitgliedern verwaltet, die Vorschläge zum Ändern und Steuern des Anwendungsvorgangs einreichen können. In Azure Confidential Ledger besitzt Microsoft Azure eine Mitgliedsidentität, sodass Governanceaktionen wie das Ersetzen fehlerhafter Knoten im Vertraulichen Ledger oder das Upgrade des Enclave-Codes ausgeführt werden können.

Beispiele

Dieser Abschnitt enthält Codeausschnitte für die folgenden Beispiele:

Post Ledger-Eintrag

const entry: LedgerEntry = {
  contents: contentBody,
};
const ledgerEntry: PostLedgerEntryParameters = {
  contentType: "application/json",
  body: entry,
};
const result = await client.path("/app/transactions").post(ledgerEntry);

Abrufen eines Ledgereintrags nach Transaktions-ID

const status = await client
  .path("/app/transactions/{transactionId}/status", transactionId)
  .get();

Alle Ledgereinträge abrufen

const ledgerEntries = await client.path("/app/transactions");

Alle Sammlungen abrufen

const result = await client.path("/app/collections").get();

Abrufen von Transaktionen für eine Sammlung

const getLedgerEntriesParams = { queryParameters: { collectionId: "my collection" } };
const ledgerEntries = await client.path("/app/transactions").get(getLedgerEntriesParams);

Listen von Enclave-Anführungszeichen

// Get enclave quotes
const enclaveQuotes = await confidentialLedger.path("/app/enclaveQuotes").get();

// Check for non-success response
if (enclaveQuotes.status !== "200") {
  throw enclaveQuotes.body.error;
}

// Log all the enclave quotes' nodeId
Object.keys(enclaveQuotes.body.enclaveQuotes).forEach((key) => {
  console.log(enclaveQuotes.body.enclaveQuotes[key].nodeId);
});

Vollständiges Beispiel

import ConfidentialLedger, { getLedgerIdentity } from "@azure-rest/confidential-ledger";
import { DefaultAzureCredential } from "@azure/identity";

export async function main() {
  // Get the signing certificate from the Confidential Ledger Identity Service
  const ledgerIdentity = await getLedgerIdentity("<my-ledger-id>");

  // Create the Confidential Ledger Client
  const confidentialLedger = ConfidentialLedger(
    "https://<ledger-name>.eastus.cloudapp.azure.com",
    ledgerIdentity.ledgerIdentityCertificate,
    new DefaultAzureCredential()
  );

  // Get enclave quotes
  const enclaveQuotes = await confidentialLedger.path("/app/enclaveQuotes").get();

  // Check for non-success response
  if (enclaveQuotes.status !== "200") {
    throw enclaveQuotes.body.error;
  }

  // Log all the enclave quotes' nodeId
  Object.keys(enclaveQuotes.body.enclaveQuotes).forEach((key) => {
    console.log(enclaveQuotes.body.enclaveQuotes[key].nodeId);
  });
}

main().catch((err) => {
  console.error(err);
});

Problembehandlung

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.

Nächste Schritte

Ausführliche Beispiele zur Verwendung dieser Bibliothek finden Sie im Beispielverzeichnis .

Mitwirken

Wenn Sie an dieser Bibliothek mitwirken möchten, lesen Sie die Anleitung für Mitwirkende, um mehr darüber zu erfahren, wie Sie den Code erstellen und testen können.

Aufrufe