Partager via

Bibliothèque de client REST Azure Confidential Ledger pour JavaScript - version 1.0.0

  • Article

Azure Confidential Ledger fournit un service de journalisation dans un registre immuable et inviolable. Dans le cadre du portefeuille d’informatique confidentielle Azure , Azure Confidential Ledger s’exécute dans des enclaves SGX. Il s’appuie sur l’infrastructure de consortium confidentiel de Microsoft Research.

Veuillez vous fier fortement à la documentation du service et à notre documentation cliente Rest pour utiliser cette bibliothèque

Liens clés :

Prise en main

Environnements actuellement pris en charge

  • Node.js version 14.x.x ou ultérieure

Prérequis

  • Un abonnement Azure.
  • Une instance en cours d’exécution du Registre confidentiel Azure.
  • Un utilisateur inscrit dans le registre confidentiel, généralement affecté lors de la création des ressources ARM , avec Administrator des privilèges.

Installez le package @azure-rest/confidential-ledger

Installez la bibliothèque de client REST Azure Condifential Ledger pour JavaScript avec npm:

npm install @azure-rest/confidential-ledger

Création et authentification du client

Utilisation d’Azure Active Directory

Ce document illustre l’utilisation de DefaultAzureCredential pour s’authentifier auprès du registre confidentiel via Azure Active Directory. Vous trouverez les variables d’environnement dans le portail Azure. Toutefois, ConfidentialLedger accepte toutes les informations d’identification @azure/d’identité .

DefaultAzureCredential gère automatiquement la plupart des scénarios de client du Kit de développement logiciel (SDK) Azure. Pour commencer, définissez les valeurs de l’ID client, de l’ID de locataire et de la clé secrète client de l’application AAD en tant que variables d’environnement : AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET.

Ensuite, DefaultAzureCredential sera en mesure d’authentifier le ConfidentialLedger client.

La création du client nécessite également l’URL et l’ID de votre registre confidentiel, que vous pouvez obtenir à partir d’Azure CLI ou du portail Azure.

Étant donné que les registres confidentiels utilisent des certificats auto-signés générés et stockés en toute sécurité dans une enclave, le certificat de signature de chaque registre confidentiel doit d’abord être récupéré à partir du service d’identité de registre confidentiel.

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

Utilisation d’un certificat client

En guise d’alternative à Azure Active Directory, les clients peuvent choisir de s’authentifier avec un certificat client dans tls mutuel plutôt que via un jeton Azure Active Directory. Pour ce type d’authentification, le client doit se faire passer un qui est composé d’un certificat et d’une CertificateCredential clé privée, tous deux au format 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,
      },
    });

Concepts clés

Entrées et transactions de registre

Chaque écriture dans Azure Confidential Ledger génère une entrée de registre immuable dans le service. Les écritures, également appelées transactions, sont identifiées de manière unique par des ID de transaction qui s’incrémentent à chaque écriture. Une fois écrites, les entrées de registre peuvent être récupérées à tout moment.

Reçus

Les modifications d’état apportées au registre confidentiel sont enregistrées dans une structure de données appelée arborescence Merkle. Pour vérifier par chiffrement que les écritures ont été correctement enregistrées, une preuve Merkle, ou un reçu, peut être récupéré pour n’importe quel ID de transaction.

Regroupements

Bien que la plupart des cas d’usage impliquent un seul registre, nous fournissons la fonctionnalité de collecte au cas où des groupes de données sémantiquement ou logiquement différents doivent être stockés dans le même registre confidentiel.

Les entrées de registre sont récupérées par leur identificateur de collection. Le registre confidentiel suppose toujours un ID de collection constant et déterminé par le service pour les entrées envoyées sans qu’une collection soit spécifiée.

Utilisateurs

Les utilisateurs sont gérés directement avec le registre confidentiel au lieu d’Azure. Les utilisateurs peuvent être basés sur AAD, identifiés par leur ID d’objet AAD, ou basés sur un certificat, identifiés par leur empreinte de certificat PEM.

Informatique confidentielle

L’informatique confidentielle Azure vous permet d’isoler et de protéger vos données pendant leur traitement dans le cloud. Azure Confidential Ledger s’exécute sur des machines virtuelles Azure Confidential Computing, offrant ainsi une protection renforcée des données avec le chiffrement des données en cours d’utilisation.

Infrastructure de consortium confidentiel

Azure Confidential Ledger est basé sur l’infrastructure CCF (Confidential Consortium Framework) open source de Microsoft Research. Sous CCF, les demandes sont gérées par un consortium de membres qui ont la possibilité de soumettre des propositions pour modifier et régir le fonctionnement de la demande. Dans Azure Confidential Ledger, Microsoft Azure possède une identité de membre, ce qui lui permet d’effectuer des actions de gouvernance telles que le remplacement de nœuds défectueux dans le registre confidentiel ou la mise à niveau du code de l’enclave.

Exemples

Cette section contient des extraits de code pour les exemples suivants :

Entrée post-registre

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

Obtenir une entrée de registre par ID de transaction

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

Obtenir toutes les entrées du registre

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

Obtenir toutes les collections

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

Obtenir des transactions pour une collection

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

Répertorier les guillemets d’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);
});

Exemple complet

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

Résolution des problèmes

Journalisation

L’activation de la journalisation peut vous aider à mieux comprendre les échecs. Pour avoir un journal des requêtes et réponses HTTP, définissez la variable d’environnement AZURE_LOG_LEVEL sur info. Vous pouvez également activer la journalisation au moment de l’exécution en appelant setLogLevel dans @azure/logger :

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

setLogLevel("info");

Pour obtenir des instructions plus détaillées sur l’activation des journaux, consultez les documents relatifs au package @azure/logger.

Étapes suivantes

Consultez le répertoire d’exemples pour obtenir des exemples détaillés sur l’utilisation de cette bibliothèque.

Contribution

Si vous souhaitez contribuer à cette bibliothèque, lisez le guide de contribution pour en savoir plus sur la génération et le test du code.

Impressions