Delen via

Azure Confidential Ledger REST-clientbibliotheek voor JavaScript - versie 1.0.0

  • Artikel

Azure Confidential Ledger biedt een service voor logboekregistratie naar een onveranderbaar, manipulatiebestendig grootboek. Als onderdeel van het Azure Confidential Computing-portfolio wordt Azure Confidential Ledger uitgevoerd in SGX-enclaves. Het is gebaseerd op het Confidential Consortium Framework van Microsoft Research.

Vertrouw sterk op de documentatie van de service en onze Rest-clientdocumenten om deze bibliotheek te gebruiken

Belangrijke koppelingen:

Aan de slag

Momenteel ondersteunde omgevingen

  • Node.js versie 14.x.x of hoger

Vereisten

  • Een Azure-abonnement.
  • Een actief exemplaar van Azure Confidential Ledger.
  • Een geregistreerde gebruiker in het vertrouwelijke grootboek, die doorgaans wordt toegewezen tijdens het maken van een ARM-resource , met Administrator bevoegdheden.

Installeer het pakket @azure-rest/confidential-ledger

Installeer de Azure Condifential Ledger REST-clientbibliotheek voor JavaScript met npm:

npm install @azure-rest/confidential-ledger

De client maken en verifiëren

Azure Active Directory gebruiken

In dit document wordt gedemonstreerd hoe u DefaultAzureCredential gebruikt voor verificatie bij het vertrouwelijke grootboek via Azure Active Directory. U vindt de omgevingsvariabelen in Azure Portal. Accepteert echter ConfidentialLedger alle @azure-/identiteitsreferenties .

DefaultAzureCredential verwerkt automatisch de meeste Azure SDK-clientscenario's. Om aan de slag te gaan, stelt u de waarden van client-id, tenant-id en clientgeheim van de AAD-toepassing in als omgevingsvariabelen: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET.

DefaultAzureCredential Vervolgens kan de ConfidentialLedger client worden geverifieerd.

Voor het maken van de client zijn ook de URL en id van uw vertrouwelijke grootboek vereist, die u kunt ophalen uit de Azure CLI of de Azure-portal.

Omdat vertrouwelijke grootboeken gebruikmaken van zelfondertekende certificaten die veilig zijn gegenereerd en opgeslagen in een enclave, moet het handtekeningcertificaat voor elk vertrouwelijk grootboek eerst worden opgehaald uit de Confidential Ledger Identity Service.

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

Een clientcertificaat gebruiken

Als alternatief voor Azure Active Directory kunnen clients ervoor kiezen om te verifiëren met een clientcertificaat in wederzijdse TLS in plaats van via een Azure Active Directory-token. Voor dit type verificatie moet de client worden doorgegeven. CertificateCredential Deze bestaat uit een certificaat en een persoonlijke sleutel, beide in PEM-indeling.

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

Belangrijkste concepten

Grootboekvermeldingen en transacties

Elke schrijfbewerking naar Azure Confidential Ledger genereert een onveranderbare grootboekvermelding in de service. Schrijfbewerkingen, ook wel transacties genoemd, worden uniek geïdentificeerd door transactie-id's die met elke schrijfbewerking worden verhoogd. Na het schrijven kunnen grootboekvermeldingen op elk gewenst moment worden opgehaald.

Ontvangsten

Statuswijzigingen in het vertrouwelijke grootboek worden opgeslagen in een gegevensstructuur die een Merkle-structuur wordt genoemd. Om cryptografisch te controleren of schrijfbewerkingen correct zijn opgeslagen, kan een Merkle-bewijs of ontvangstbewijs worden opgehaald voor elke transactie-id.

Verzamelingen

Hoewel de meeste use cases betrekking hebben op één grootboek, bieden we de verzamelingsfunctie voor het geval semantisch of logisch verschillende groepen gegevens moeten worden opgeslagen in hetzelfde vertrouwelijke grootboek.

Grootboekvermeldingen worden opgehaald door hun verzamelings-id. Het vertrouwelijke grootboek gaat altijd uit van een constante, door de service bepaalde verzamelings-id voor vermeldingen die worden verzonden zonder dat er een verzameling is opgegeven.

Gebruikers

Gebruikers worden rechtstreeks beheerd met het vertrouwelijke grootboek in plaats van via Azure. Gebruikers kunnen op AAD zijn gebaseerd, geïdentificeerd aan de hand van hun AAD-object-id of op basis van certificaten, geïdentificeerd door hun PEM-certificaatvingerafdruk.

Confidential Computing

Met Azure Confidential Computing kunt u uw gegevens isoleren en beveiligen terwijl deze in de cloud worden verwerkt. Azure Confidential Ledger wordt uitgevoerd op virtuele machines van Azure Confidential Computing en biedt zo een betere gegevensbeveiliging met versleuteling van gegevens die in gebruik zijn.

Confidential Consortium Framework

Azure Confidential Ledger is gebaseerd op het opensource Confidential Consortium Framework (CCF) van Microsoft Research. Onder CCF worden toepassingen beheerd door een consortium van leden met de mogelijkheid om voorstellen in te dienen om de toepassingsbewerking te wijzigen en te beheren. In Azure Confidential Ledger is Microsoft Azure eigenaar van een lididentiteit, zodat deze beheeracties kan uitvoeren, zoals het vervangen van beschadigde knooppunten in het vertrouwelijke grootboek of het upgraden van de enclavecode.

Voorbeelden

Deze sectie bevat codefragmenten voor de volgende voorbeelden:

Post Ledger Entry

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

Een grootboekvermelding ophalen op transactie-id

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

Alle grootboekvermeldingen ophalen

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

Alle verzamelingen ophalen

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

Transacties voor een verzameling ophalen

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

Enclave-aanhalingstekens vermelden

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

Compleet voorbeeld

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

Problemen oplossen

Logboekregistratie

Het inschakelen van logboekregistratie kan helpen bij het ontdekken van nuttige informatie over fouten. Als u een logboek met HTTP-aanvragen en -antwoorden wilt zien, stelt u de AZURE_LOG_LEVEL omgevingsvariabele in op info. U kunt logboekregistratie ook tijdens runtime inschakelen door aan te roepen setLogLevel in de @azure/logger:

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

setLogLevel("info");

Voor meer gedetailleerde instructies over het inschakelen van logboeken kunt u de @azure-/loggerpakketdocumenten bekijken.

Volgende stappen

Bekijk de map met voorbeelden voor gedetailleerde voorbeelden van het gebruik van deze bibliotheek.

Bijdragen

Als u een bijdrage wilt leveren aan deze bibliotheek, leest u de handleiding voor bijdragen voor meer informatie over het bouwen en testen van de code.

Weergaven