Libreria client REST riservato per JavaScript - versione 1.0.0

Il ledger riservato di Azure offre un servizio per la registrazione a un ledger non modificabile e manomissione. Nell'ambito del portfolio di Azure Confidential Computing , il ledger riservato di Azure viene eseguito in enclave SGX. Si basa su Microsoft Research's Confidential Consortium Framework.

Per usare questa libreria, fare affidamento sulla documentazione del servizio e sulla documentazionedel client Rest

Collegamenti principali:

• Codice sorgente
• Pacchetto (NPM)
• Documentazione di riferimento delle API
• Documentazione del prodotto

Introduzione

Ambienti attualmente supportati

• Node.js versione 14.x.x o successiva

Prerequisiti

• Una sottoscrizione di Azure.
• Istanza in esecuzione di Azure Confidential Ledger.
• Un utente registrato nel Ledger riservato, in genere assegnato durante la creazione di risorse arm , con Administrator privilegi.

Installare il pacchetto @azure-rest/confidential-ledger

Installare la libreria client REST di Azure Condifential Ledger per JavaScript con npm:

npm install @azure-rest/confidential-ledger

Creazione e autenticazione del client

Uso di Azure Active Directory

Questo documento illustra l'uso di DefaultAzureCredential per l'autenticazione al Ledger riservato tramite Azure Active Directory. È possibile trovare le variabili di ambiente nel portale di Azure. Accetta tuttavia ConfidentialLedger tutte le credenziali @azure/identity .

DefaultAzureCredential gestirà automaticamente la maggior parte degli scenari client di Azure SDK. Per iniziare, impostare i valori di ID client, ID tenant e segreto client dell'applicazione AAD come variabili di ambiente: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET.

DefaultAzureCredential Sarà quindi possibile autenticare il ConfidentialLedger client.

La creazione del client richiede anche l'URL e l'ID del ledger riservato, che è possibile ottenere dall'interfaccia della riga di comando di Azure o dal portale di Azure.

Poiché i ledgger riservati usano certificati autofirmati generati e archiviati in un enclave, il certificato di firma per ogni ledger riservato deve essere recuperato prima dal servizio identità del ledger riservato.

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

Uso di un certificato client

In alternativa ad Azure Active Directory, i client possono scegliere di eseguire l'autenticazione con un certificato client in TLS reciproco anziché tramite un token di Azure Active Directory. Per questo tipo di autenticazione, il client deve essere passato a un CertificateCredential che è composto da un certificato e una chiave privata, entrambi in formato PEM.

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

Concetti chiave

Voci e transazioni ledger

Ogni scrittura in Azure Confidential Ledger genera una voce del ledger non modificabile nel servizio. Le scritture, definite anche transazioni, sono identificate in modo univoco dagli ID transazione che aumentano con ogni scrittura. Una volta scritte, le voci del ledger possono essere recuperate in qualsiasi momento.

Receipts

Le modifiche dello stato apportate al Ledger riservato vengono salvate in una struttura di dati denominata albero Merkle. Per verificare in modo crittografico che le scritture siano state salvate correttamente, è possibile recuperare una prova Merkle o una ricevuta per qualsiasi ID transazione.

Raccolte

Anche se la maggior parte dei casi d'uso coinvolgerà un ledger, è necessario fornire la funzionalità di raccolta in caso di gruppi semantici o logicamente diversi di dati da archiviare nello stesso ledger riservato.

Le voci ledger vengono recuperate dall'identificatore della raccolta. Il ledger riservato presuppone sempre un ID raccolta costante, determinato dal servizio per le voci inviate senza una raccolta specificata.

Utenti

Gli utenti vengono gestiti direttamente con il Ledger riservato anziché tramite Azure. Gli utenti possono essere basati su AAD, identificati dall'ID oggetto AAD o dal certificato, identificati dall'impronta digitale del certificato PEM.

Confidential computing

Azure Confidential Computing consente di isolare e proteggere i dati durante l'elaborazione nel cloud. Il ledger riservato di Azure viene eseguito in macchine virtuali di Calcolo riservato di Azure, offrendo così una maggiore protezione dei dati con crittografia dei dati in uso.

Framework del consorzio riservato

Il ledger riservato di Azure è basato su Microsoft Research's open source Confidential Consortium Framework (CCF).Azure Confidential Ledger è basato su Microsoft Research's open source Confidential Consortium Framework (CCF). In CCF, le applicazioni vengono gestite da un consorzio di membri con la possibilità di inviare proposte per modificare e gestire l'operazione dell'applicazione. In Azure Confidential Ledger, Microsoft Azure possiede un'identità membro, consentendo l'esecuzione di azioni di governance come la sostituzione di nodi non integri nel Ledger riservato o l'aggiornamento del codice enclave.

Esempio

Questa sezione contiene frammenti di codice per gli esempi seguenti:

• Voce Post Ledger
• Ottenere una voce ledger in base all'ID transazione
• Ottenere tutte le voci del ledger
• Ottenere tutte le raccolte
• Ottenere transazioni per una raccolta
• Elenca virgolette enclave

Voce Post Ledger

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

Ottenere una voce ledger in base all'ID transazione

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

Ottenere tutte le voci del ledger

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

Ottenere tutte le raccolte

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

Ottenere transazioni per una raccolta

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

Elenca virgolette enclave

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

Esempio completo

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

Risoluzione dei problemi

Registrazione

L'abilitazione della registrazione consente di individuare informazioni utili sugli errori. Per visualizzare un log di richieste e risposte HTTP, impostare la variabile di ambiente AZURE_LOG_LEVEL su info. In alternativa, la registrazione può essere abilitata in fase di esecuzione chiamando setLogLevel in @azure/logger:

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

setLogLevel("info");

Per istruzioni più dettagliate su come abilitare i log, è possibile esaminare la documentazione del pacchetto @azure/logger.

Passaggi successivi

Per esempi dettagliati su come usare questa libreria, vedere la directory degli esempi .

Contributo

Per contribuire a questa libreria, leggere la guida ai contributi per altre informazioni su come compilare e testare il codice.

Progetti correlati

• Microsoft Azure SDK per JavaScript