Compartir a través de

Biblioteca cliente REST de Azure Confidential Ledger para JavaScript: versión 1.0.0

Azure Confidential Ledger proporciona un servicio para el registro en un libro de contabilidad inmutable y a prueba de alteraciones. Como parte de la cartera de computación confidencial de Azure , Azure Confidential Ledger se ejecuta en enclaves sgx. Se basa en el marco del consorcio confidencial de Microsoft Research.

Confíe en gran medida en la documentación del servicio y en la documentación del cliente rest para usar esta biblioteca.

Vínculos principales:

Introducción

Entornos admitidos actualmente

  • Node.js versión 14.x.x o superior

Requisitos previos

  • Una suscripción de Azure.
  • Una instancia en ejecución de Azure Confidential Ledger.
  • Un usuario registrado en Confidential Ledger, normalmente asignado durante la creación de recursos de ARM , con Administrator privilegios.

Instalar el paquete @azure-rest/confidential-ledger

Instale la biblioteca cliente REST de Azure Condifential Ledger para JavaScript con npm:

npm install @azure-rest/confidential-ledger

Creación y autenticación del cliente

Uso de Azure Active Directory

En este documento se muestra cómo usar DefaultAzureCredential para autenticarse en Confidential Ledger a través de Azure Active Directory. Puede encontrar las variables de entorno en Azure Portal. Sin embargo, ConfidentialLedger acepta cualquier credencial de @azure/identidad .

DefaultAzureCredential controlará automáticamente la mayoría de los escenarios de cliente del SDK de Azure. Para empezar, establezca los valores del identificador de cliente, el identificador de inquilino y el secreto de cliente de la aplicación de AAD como variables de entorno: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET.

A continuación, DefaultAzureCredential podrá autenticar al ConfidentialLedger cliente.

La creación del cliente también requiere la dirección URL y el identificador de Confidential Ledger, que puede obtener desde la CLI de Azure o Azure Portal.

Dado que Confidential Ledgers usa certificados autofirmados generados y almacenados de forma segura en un enclave, primero se debe recuperar el certificado de firma de cada libro de contabilidad confidencial de 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);

Uso de un certificado de cliente

Como alternativa a Azure Active Directory, los clientes pueden optar por autenticarse con un certificado de cliente en TLS mutuo en lugar de a través de un token de Azure Active Directory. Para este tipo de autenticación, el cliente debe pasarse un CertificateCredential que se compone de un certificado y una clave privada, ambos en 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,
      },
    });

Conceptos clave

Entradas y transacciones del libro de contabilidad

Cada escritura en Azure Confidential Ledger genera una entrada de libro de contabilidad inmutable en el servicio. Las escrituras, también conocidas como transacciones, se identifican de forma única mediante identificadores de transacción que se incrementan con cada escritura. Una vez escritas, las entradas del libro de contabilidad se pueden recuperar en cualquier momento.

Receipts

Los cambios de estado en Confidential Ledger se guardan en una estructura de datos denominada árbol Merkle. Para comprobar criptográficamente que las escrituras se guardaron correctamente, se puede recuperar una prueba de Merkle o recibo para cualquier identificador de transacción.

Colecciones

Aunque la mayoría de los casos de uso implicarán un libro de contabilidad, proporcionamos la característica de recopilación en caso de que se almacenen de forma semántica o lógicamente diferentes grupos de datos en el mismo libro de contabilidad confidencial.

Las entradas del libro de contabilidad se recuperan mediante su identificador de colección. Confidential Ledger siempre asume un identificador de colección constante determinado por el servicio para las entradas enviadas sin una colección especificada.

Usuarios

Los usuarios se administran directamente con Confidential Ledger en lugar de a través de Azure. Los usuarios pueden estar basados en AAD, identificados por su identificador de objeto de AAD o basado en certificados, identificados por su huella digital del certificado PEM.

Computación confidencial

La computación confidencial de Azure permite aislar y proteger los datos mientras se procesan en la nube. Azure Confidential Ledger se ejecuta en máquinas virtuales de computación confidencial de Azure, lo que proporciona una protección de datos más sólida con el cifrado de datos en uso.

Confidential Consortium Framework

Azure Confidential Ledger se basa en el marco de consorcio confidencial (CCF) de código abierto de Microsoft Research. En ccF, las aplicaciones son administradas por un consorcio de miembros con la capacidad de enviar propuestas para modificar y controlar la operación de aplicación. En Azure Confidential Ledger, Microsoft Azure posee una identidad de miembro, lo que le permite realizar acciones de gobernanza como reemplazar nodos incorrectos en Confidential Ledger o actualizar el código de enclave.

Ejemplos

Esta sección contiene fragmentos de código para los ejemplos siguientes:

Entrada del libro de contabilidad posterior

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

Obtener una entrada de libro de contabilidad por identificador de transacción

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

Obtener todas las entradas del libro de contabilidad

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

Obtener todas las colecciones

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

Obtener transacciones para una colección

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

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

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

Solución de problemas

Registro

La habilitación del registro puede ayudar a descubrir información útil sobre los errores. Para ver un registro de solicitudes y respuestas HTTP, establezca la variable de entorno AZURE_LOG_LEVEL en info. Como alternativa, el registro se puede habilitar en tiempo de ejecución llamando a setLogLevel en @azure/logger:

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

setLogLevel("info");

Para obtener instrucciones más detalladas sobre cómo habilitar los registros, consulte los documentos del paquete @azure/logger.

Pasos siguientes

Eche un vistazo al directorio de ejemplos para obtener ejemplos detallados sobre cómo usar esta biblioteca.

Contribuciones

Si desea contribuir a esta biblioteca, lea la guía de contribución para obtener más información sobre cómo compilar y probar el código.

Impresiones

  • Last updated on