Partilhar via

Biblioteca de cliente REST do Azure Confidential Ledger para JavaScript – versão 1.0.0

  • Artigo

O Azure Confidential Ledger fornece um serviço para registar num livro razão imutável e à prova de adulteração. Como parte do portefólio de Computação Confidencial do Azure , o Azure Confidential Ledger é executado em enclaves SGX. Baseia-se no Framework do Consórcio Confidencial da Microsoft Research.

Confie fortemente na documentação do serviço e nos nossos documentos do cliente Rest para utilizar esta biblioteca

Ligações principais:

Introdução

Ambientes atualmente suportados

  • Node.js versão 14.x.x ou superior

Pré-requisitos

  • Uma subscrição do Azure.
  • Uma instância em execução do Azure Confidential Ledger.
  • Um utilizador registado no Livro Razão Confidencial, normalmente atribuído durante a criação de recursos do ARM , com Administrator privilégios.

Instalar o pacote @azure-rest/confidential-ledger

Instale a biblioteca de cliente REST Do Azure Condifential Ledger para JavaScript com npm:

npm install @azure-rest/confidential-ledger

Criar e Autenticar o cliente

Utilizar o Azure Active Directory

Este documento demonstra a utilização de DefaultAzureCredential para autenticar no Livro Razão Confidencial através do Azure Active Directory. Pode encontrar as variáveis de ambiente no Portal do Azure. No entanto, ConfidentialLedger aceita qualquer credencial de @azure/identidade .

DefaultAzureCredential processará automaticamente a maioria dos cenários de cliente do SDK do Azure. Para começar, defina os valores do ID de cliente, do ID do inquilino e do segredo do cliente da aplicação do AAD como variáveis de ambiente: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET.

Em seguida, DefaultAzureCredential poderá autenticar o ConfidentialLedger cliente.

A criação do cliente também requer o URL e o ID do Livro Razão Confidencial, que pode obter a partir da CLI do Azure ou do Portal do Azure.

Uma vez que os Livros RazãoIs Confidenciais utilizam certificados autoassinados gerados e armazenados em segurança num enclave, o certificado de assinatura de cada Livro Razão Confidencial tem primeiro de ser obtido a partir do Serviço de Identidade Do Livro Razão Confidencial.

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

Utilizar um certificado de cliente

Como alternativa ao Azure Active Directory, os clientes podem optar por autenticar com um certificado de cliente no TLS mútuo em vez de através de um token do Azure Active Directory. Para este tipo de autenticação, é necessário transmitir ao cliente um CertificateCredential que é composto por um certificado e chave privada, ambos no 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,
      },
    });

Conceitos-chave

Entradas e transações de livros razão

Cada escrita no Azure Confidential Ledger gera uma entrada de livro razão imutável no serviço. As escritas, também conhecidas como transações, são identificadas exclusivamente por IDs de transação que incrementam com cada escrita. Uma vez escritas, as entradas de livros razão podem ser obtidas em qualquer altura.

Recibos

As alterações de estado ao Livro Razão Confidencial são guardadas numa estrutura de dados denominada árvore Merkle. Para verificar criptograficamente se as escritas foram guardadas corretamente, é possível obter uma prova Merkle ou um recibo para qualquer ID de transação.

Coleções

Embora a maioria dos casos de utilização envolva um livro razão, fornecemos a funcionalidade de coleção no caso de grupos de dados semanticamente ou logicamente diferentes precisarem de ser armazenados no mesmo Livro Razão Confidencial.

As entradas de razão são obtidas pelo identificador de coleção. O Livro Razão Confidencial assumirá sempre um ID de coleção constante e determinado pelo serviço para as entradas submetidas sem uma coleção especificada.

Utilizadores

Os utilizadores são geridos diretamente com o Livro Razão Confidencial em vez de através do Azure. Os utilizadores podem ser baseados no AAD, identificados pelo respetivo ID de objeto do AAD ou baseado em certificado, identificados pela respetiva impressão digital do certificado PEM.

Computação confidencial

A Computação Confidencial do Azure permite-lhe isolar e proteger os seus dados enquanto estão a ser processados na cloud. O Azure Confidential Ledger é executado em máquinas virtuais de Computação Confidencial do Azure, proporcionando assim uma proteção de dados mais forte com a encriptação de dados em utilização.

Confidencial Consortium Framework

O Azure Confidential Ledger baseia-se no Framework de Consórcio Confidencial (CCF) open source da Microsoft Research. Em CCF, as aplicações são geridas por um consórcio de membros com a capacidade de submeter propostas para modificar e governar a operação de aplicação. No Azure Confidential Ledger, o Microsoft Azure detém uma identidade de membro, permitindo-lhe executar ações de governação, como substituir nós em mau estado de funcionamento no Livro Razão Confidencial ou atualizar o código do enclave.

Exemplos

Esta secção contém fragmentos de código para os seguintes exemplos:

Entrada Post Ledger

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

Obter um ID de Entrada Por Transação do Livro Razão

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

Obter Todas as Entradas do Livro Razão

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

Obter Todas as Coleções

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

Obter Transações para uma Coleção

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

Listar Aspas do 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);
});

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

Resolução de problemas

Registo

Ativar o registo pode ajudar a descobrir informações úteis sobre falhas. Para ver um registo de pedidos HTTP e respostas, defina a variável de AZURE_LOG_LEVEL ambiente como info. Em alternativa, o registo pode ser ativado no runtime ao chamar setLogLevel no @azure/logger:

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

setLogLevel("info");

Para obter instruções mais detalhadas sobre como ativar registos, pode ver os documentos do pacote de @azure/logger.

Passos seguintes

Veja o diretório de exemplos para obter exemplos detalhados sobre como utilizar esta biblioteca.

Contribuir

Se quiser contribuir para esta biblioteca, leia o guia de contribuição para saber mais sobre como criar e testar o código.

Impressões