Compartilhar via

Biblioteca de clientes REST do Razão Confidencial do Azure para JavaScript – versão 1.0.0

  • Artigo

O Razão Confidencial do Azure fornece um serviço para fazer logon em um razão imutável e à prova de adulterações. Como parte do portfólio de Computação Confidencial do Azure , o Razão Confidencial do Azure é executado em enclaves SGX. Ele se baseia na Estrutura de Consórcio Confidencial da Microsoft Research.

Confie fortemente na documentação do serviço e nos documentos do cliente Rest para usar essa biblioteca

Links principais:

Introdução

Ambientes com suporte no momento

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

Pré-requisitos

  • Uma assinatura do Azure.
  • Uma instância em execução do Razão Confidencial do Azure.
  • Um usuário registrado no 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 clientes REST do Razão Condifential do Azure para JavaScript com npm:

npm install @azure-rest/confidential-ledger

Criando e autenticando o cliente

Como usar o Azure Active Directory

Este documento demonstra como usar DefaultAzureCredential para autenticar no Razão Confidencial por meio do Azure Active Directory. Você pode encontrar as variáveis de ambiente no Portal do Azure. No entanto, ConfidentialLedger aceita qualquer credencial de @azure/identidade .

DefaultAzureCredential lidará automaticamente com a maioria dos cenários de cliente do SDK do Azure. Para começar, defina os valores da ID do cliente, da ID do locatário e do segredo do cliente do aplicativo AAD como variáveis de ambiente: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET.

Em seguida, DefaultAzureCredential será possível autenticar o ConfidentialLedger cliente.

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

Como os Razãos Confidenciais usam certificados autoassinados gerados e armazenados com segurança em um enclave, o certificado de autenticação para cada Razão Confidencial deve primeiro ser recuperado do Serviço de Identidade do 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);

Usando um certificado de cliente

Como alternativa ao Azure Active Directory, os clientes podem optar por autenticar com um certificado de cliente em TLS mútuo em vez de por meio de um token do Azure Active Directory. Para esse tipo de autenticação, o cliente precisa ser passado um CertificateCredential que é composto por um certificado e uma 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,
      },
    });

Principais conceitos

Entradas e transações do razão

Cada gravação no Razão Confidencial do Azure gera uma entrada do razão imutável no serviço. As gravações, também conhecidas como transações, são identificadas exclusivamente por IDs de transação que incrementam com cada gravação. Depois de gravadas, as entradas do razão podem ser recuperadas a qualquer momento.

Recebimentos

As alterações de estado no Razão Confidencial são salvas em uma estrutura de dados chamada árvore Merkle. Para verificar criptograficamente se as gravações foram salvas corretamente, uma prova merkle ou recibo pode ser recuperada para qualquer ID de transação.

Coleções

Embora a maioria dos casos de uso envolva um razão, fornecemos o recurso de coleção caso grupos de dados semanticamente ou logicamente diferentes precisem ser armazenados no mesmo Razão Confidencial.

As entradas do razão são recuperadas pelo identificador de coleção. O Razão Confidencial sempre assumirá uma ID de coleção constante determinada pelo serviço para entradas enviadas sem uma coleção especificada.

Usuários

Os usuários são gerenciados diretamente com o Razão Confidencial em vez de por meio do Azure. Os usuários podem ser baseados no AAD, identificados por sua ID de objeto do AAD ou com base em certificado, identificados pela impressão digital do certificado PEM.

Computação Confidencial

A Computação Confidencial do Azure permite isolar e proteger seus dados enquanto eles estão sendo processados na nuvem. O Razão Confidencial do Azure é executado em máquinas virtuais de Computação Confidencial do Azure, fornecendo proteção de dados mais forte com criptografia de dados em uso.

Estrutura de Consórcio Confidencial

O Razão Confidencial do Azure baseia-se no CCF (Confidential Consortium Framework) de software livre da Microsoft Research. No CCF, os aplicativos são gerenciados por um consórcio de membros com a capacidade de enviar propostas para modificar e controlar a operação do aplicativo. No Razão Confidencial do Azure, o Microsoft Azure possui uma identidade de membro, permitindo que ele execute ações de governança, como substituir nós não íntegros no Razão Confidencial ou atualizar o código de enclave.

Exemplos

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

Entrada pós-razão

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

Obter uma entrada do razão por ID da transação

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

Obter todas as entradas do 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 de 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);
});

Solução de problemas

Log

A habilitação do log pode ajudar a descobrir informações úteis sobre falhas. Para ver um log de solicitações e respostas HTTP, defina a variável de ambiente AZURE_LOG_LEVEL como info. Como alternativa, o log pode ser habilitado no runtime chamando setLogLevel em @azure/logger:

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

setLogLevel("info");

Para obter instruções mais detalhadas sobre como habilitar logs, veja os documentos do pacote @azure/logger.

Próximas etapas

Dê uma olhada no diretório de exemplos para obter exemplos detalhados sobre como usar essa biblioteca.

Contribuição

Se você quiser contribuir com essa biblioteca, leia o guia de contribuição para saber como criar e testar o código.

Impressões