Sdílet prostřednictvím

Klientská knihovna REST služby Azure Confidential Ledger pro JavaScript – verze 1.0.0

  • Článek

Azure Confidential Ledger poskytuje službu pro protokolování do neměnné hlavní knihy odolné proti manipulaci. Jako součást portfolia Azure Confidential Computing běží Azure Confidential Ledger v enklávech SGX. Je postaven na architektuře důvěrného konsorcia společnosti Microsoft Research.

Při používání této knihovny se do značné míry spolehněte na dokumentaci ke službě a naše klientské dokumenty REST .

Klíčové odkazy:

Začínáme

Aktuálně podporovaná prostředí

  • Node.js verze 14.x.x nebo vyšší

Požadavky

  • Předplatné Azure
  • Spuštěná instance služby Azure Confidential Ledger.
  • Registrovaný uživatel v důvěrném registru, který se obvykle přiřazuje při vytváření prostředku ARM , s oprávněními Administrator .

Nainstalujte balíček @azure-rest/confidential-ledger.

Nainstalujte klientskou knihovnu REST azure Condifential Ledger pro JavaScript pomocí npmpříkazu :

npm install @azure-rest/confidential-ledger

Vytvoření a ověření klienta

Použití Azure Active Directory

Tento dokument ukazuje použití DefaultAzureCredential k ověření v důvěrném registru přes Azure Active Directory. Proměnné prostředí najdete na webu Azure Portal. Akceptuje ConfidentialLedger však všechny přihlašovací údaje @azure/identity .

DefaultAzureCredential automaticky zpracuje většinu klientských scénářů sady Azure SDK. Začněte nastavením hodnot ID klienta, ID tenanta a tajného klíče klienta aplikace AAD jako proměnných prostředí: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET.

DefaultAzureCredential Pak bude moct klienta ověřitConfidentialLedger.

Vytvoření klienta také vyžaduje adresu URL a ID vašeho důvěrného registru, které můžete získat z Azure CLI nebo webu Azure Portal.

Vzhledem k tomu, že důvěrné knihy používají certifikáty podepsané svým držitelem bezpečně vygenerované a uložené v enklávě, podpisový certifikát pro každou důvěrné ledger musí být nejprve načten ze služby 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);

Použití klientského certifikátu

Jako alternativu k Azure Active Directory se klienti můžou rozhodnout pro ověřování pomocí klientského certifikátu ve vzájemném protokolu TLS místo pomocí tokenu Azure Active Directory. Pro tento typ ověřování je potřeba klientovi předat CertificateCredential certifikát, který se skládá z certifikátu a soukromého klíče, a to jak ve formátu 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,
      },
    });

Klíčové koncepty

Položky a transakce hlavní knihy

Každý zápis do služby Azure Confidential Ledger vygeneruje neměnnou položku registru ve službě. Zápisy, označované také jako transakce, jsou jednoznačně identifikovány ID transakcí, která se s každým zápisem zvýší. Po zápisu mohou být položky registru kdykoli načteny.

Účtenky

Změny stavu v důvěrném registru se ukládají do datové struktury označované jako Merkle tree. Chcete-li kryptograficky ověřit, že zápisy byly správně uloženy, je možné pro jakékoli ID transakce načíst doklad Merkle nebo potvrzení.

Kolekce

I když většina případů použití zahrnuje jednu knihu, poskytujeme funkci shromažďování pro případ, že by ve stejné důvěrné registru bylo potřeba uložit sémanticky nebo logicky různé skupiny dat.

Položky hlavní knihy se načítají podle identifikátoru kolekce. Confidential Ledger bude vždy předpokládat konstantní ID kolekce určené službou pro položky odeslané bez zadané kolekce.

Uživatelé

Uživatelé jsou spravováni přímo pomocí důvěrného registru místo prostřednictvím Azure. Uživatelé můžou být založeni na AAD, identifikovaní svým ID objektu AAD nebo na základě certifikátů a identifikovaní otiskem jejich certifikátu PEM.

Důvěrné výpočetní operace

Azure Confidential Computing umožňuje izolovat a chránit vaše data během jejich zpracování v cloudu. Služba Azure Confidential Ledger běží na virtuálních počítačích Azure Confidential Computing, a poskytuje tak silnější ochranu dat se šifrováním užitých dat.

Důvěrné konsorcium Framework

Služba Azure Confidential Ledger je postavená na opensourcové architektuře CcF (Confidential Consortium Framework) společnosti Microsoft Research. V rámci CCF jsou aplikace spravovány konsorciem členů s možností odesílat návrhy na úpravy a řízení provozu aplikace. Ve službě Azure Confidential Ledger vlastní Microsoft Azure identitu člena, která jí umožňuje provádět akce zásad správného řízení, jako je nahrazení uzlů, které nejsou v pořádku, v důvěrném registru nebo upgrade kódu enklávy.

Příklady

Tato část obsahuje fragmenty kódu pro následující ukázky:

Položka poštovní knihy

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

Získání položky hlavní knihy podle ID transakce

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

Získat všechny položky hlavní knihy

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

Získat všechny kolekce

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

Získání transakcí pro kolekci

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

Výpis uvozovek enklávy

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

Úplný příklad

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

Řešení potíží

protokolování

Povolení protokolování může pomoct odhalit užitečné informace o selháních. Pokud chcete zobrazit protokol požadavků a odpovědí HTTP, nastavte proměnnou AZURE_LOG_LEVEL prostředí na info. Případně je možné protokolování povolit za běhu voláním setLogLevel v :@azure/logger

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

setLogLevel("info");

Podrobnější pokyny k povolení protokolů najdete v dokumentaci k balíčkům @azure/protokolovacího nástroje.

Další kroky

Podrobné příklady použití této knihovny najdete v adresáři samples .

Přispívání

Pokud chcete přispívat do této knihovny, přečtěte si prosím průvodce přispívání , kde se dozvíte více o tom, jak sestavit a otestovat kód.

Imprese