Udostępnij za pośrednictwem

Biblioteka klienta REST poufnego rejestru platformy Azure dla języka JavaScript — wersja 1.0.0

  • Artykuł

Rejestr poufny platformy Azure udostępnia usługę rejestrowania w niezmiennym, odpornym na naruszenia rejestrze. W ramach portfolio poufnego przetwarzania platformy Azure rejestr poufny platformy Azure działa w enklawie SGX. Jest ona oparta na strukturze poufnego konsorcjum Microsoft Research.

W dużej mierze polegaj na dokumentacji usługi i dokumentacji klienta REST , aby korzystać z tej biblioteki

Kluczowe linki:

Wprowadzenie

Obecnie obsługiwane środowiska

  • Node.js w wersji 14.x.x lub nowszej

Wymagania wstępne

  • Subskrypcja platformy Azure.
  • Uruchomione wystąpienie rejestru poufnego platformy Azure.
  • Zarejestrowany użytkownik w rejestrze poufnym, zazwyczaj przypisany podczas tworzenia zasobów usługi ARM z uprawnieniami Administrator .

Instalowanie pakietu @azure-rest/confidential-ledger

Zainstaluj bibliotekę klienta REST usługi Azure Condifential Ledger dla języka JavaScript przy użyciu polecenia npm:

npm install @azure-rest/confidential-ledger

Tworzenie i uwierzytelnianie klienta

Korzystanie z usługi Azure Active Directory

W tym dokumencie pokazano, jak używać domyślnejazureCredential do uwierzytelniania w rejestrze poufnym za pośrednictwem usługi Azure Active Directory. Zmienne środowiskowe można znaleźć w witrynie Azure Portal. ConfidentialLedger Akceptuje jednak wszelkie poświadczenia @azure/tożsamości.

DefaultAzureCredential program automatycznie obsłuży większość scenariuszy klienta zestawu Azure SDK. Aby rozpocząć, ustaw wartości identyfikatora klienta, identyfikatora dzierżawy i wpisu tajnego klienta aplikacji usługi AAD jako zmienne środowiskowe: AZURE_CLIENT_ID, , AZURE_CLIENT_SECRETAZURE_TENANT_ID.

DefaultAzureCredential Następnie będzie można uwierzytelnić ConfidentialLedger klienta.

Utworzenie klienta wymaga również adresu URL i identyfikatora poufnego rejestru, który można pobrać z interfejsu wiersza polecenia platformy Azure lub witryny Azure Portal.

Ponieważ rejestry poufne używają certyfikatów z podpisem własnym wygenerowanych i przechowywanych w enklawie, certyfikat podpisywania dla każdego poufnego rejestru musi zostać najpierw pobrany z usługi tożsamości poufnego rejestru.

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

Używanie certyfikatu klienta

Alternatywnie dla usługi Azure Active Directory klienci mogą zdecydować się na uwierzytelnianie przy użyciu certyfikatu klienta w wzajemnym protokole TLS zamiast za pośrednictwem tokenu usługi Azure Active Directory. W przypadku tego rodzaju uwierzytelniania klient musi zostać przekazany CertificateCredential , który składa się z certyfikatu i klucza prywatnego, zarówno w formacie 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,
      },
    });

Kluczowe pojęcia

Wpisy i transakcje rejestru

Każdy zapis w rejestrze poufnym platformy Azure generuje niezmienny wpis rejestru w usłudze. Zapisy, nazywane również transakcjami, są jednoznacznie identyfikowane przez identyfikatory transakcji, które przyrostują każdy zapis. Po zapisaniu wpisy rejestru mogą być pobierane w dowolnym momencie.

Rachunki

Zmiany stanu w rejestrze poufnym są zapisywane w strukturze danych nazywanej drzewem Merkle. Aby kryptograficznie sprawdzić, czy zapisy zostały poprawnie zapisane, dowód merkle lub potwierdzenie, można pobrać dla dowolnego identyfikatora transakcji.

Kolekcje

Podczas gdy większość przypadków użycia będzie obejmować jeden rejestr, udostępniamy funkcję zbierania w przypadku, gdy semantycznie lub logicznie różne grupy danych muszą być przechowywane w tym samym rejestrze poufnym.

Wpisy rejestru są pobierane przez ich identyfikator kolekcji. Rejestr poufny zawsze przyjmuje stały identyfikator kolekcji określonej przez usługę dla wpisów przesłanych bez określonej kolekcji.

Użytkownicy

Użytkownicy są zarządzani bezpośrednio przy użyciu rejestru poufnego zamiast za pośrednictwem platformy Azure. Użytkownicy mogą być oparte na usłudze AAD, identyfikowane przez identyfikator obiektu usługi AAD lub oparte na certyfikatach, identyfikowane przez odcisk palca certyfikatu PEM.

Poufne przetwarzanie

Poufne przetwarzanie na platformie Azure umożliwia izolowanie i ochronę danych podczas ich przetwarzania w chmurze. Rejestr poufny platformy Azure działa na maszynach wirtualnych usługi Azure Confidential Computing, co zapewnia lepszą ochronę danych przy użyciu szyfrowania danych.

Poufne konsorcjum Framework

Poufne rejestry platformy Azure są oparte na strukturze Poufne konsorcjum (CCF) firmy Microsoft Research. W ramach programu CCF aplikacje są zarządzane przez konsorcjum członków z możliwością przesyłania propozycji do modyfikowania i zarządzania operacją aplikacji. W rejestrze poufnym platformy Azure platforma Microsoft Azure jest właścicielem tożsamości członka, umożliwiając jej wykonywanie akcji ładu, takich jak zastępowanie węzłów w złej kondycji w rejestrze poufnym lub uaktualnianie kodu enklawy.

Przykłady

Ta sekcja zawiera fragmenty kodu dla następujących przykładów:

Wpis rejestru

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

Pobieranie wpisu rejestru według identyfikatora transakcji

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

Pobieranie wszystkich wpisów rejestru

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

Pobieranie wszystkich kolekcji

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

Pobieranie transakcji dla kolekcji

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

Lista cudzysłowów enklawy

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

Pełny przykład

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

Rozwiązywanie problemów

Rejestrowanie

Włączenie rejestrowania może pomóc odkryć przydatne informacje o błędach. Aby wyświetlić dziennik żądań HTTP i odpowiedzi, ustaw zmienną AZURE_LOG_LEVEL środowiskową na info. Możesz też włączyć rejestrowanie w czasie wykonywania, wywołując polecenie w elemecie setLogLevel@azure/logger:

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

setLogLevel("info");

Aby uzyskać bardziej szczegółowe instrukcje dotyczące włączania dzienników, zapoznaj się z dokumentami dotyczącymi pakietu @azure/rejestratora.

Następne kroki

Zapoznaj się z katalogiem samples , aby uzyskać szczegółowe przykłady dotyczące sposobu korzystania z tej biblioteki.

Współtworzenie

Jeśli chcesz współtworzyć tę bibliotekę, przeczytaj przewodnik współtworzenia , aby dowiedzieć się więcej na temat sposobu kompilowania i testowania kodu.

Wrażenia