你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

适用于 JavaScript 的 Azure 机密账本 REST 客户端库 - 版本 1.0.0

项目
04/05/2023

Azure 机密账本提供用于记录到不可变、防篡改账本的服务。作为 Azure 机密计算产品组合的一部分，Azure 机密账本在 SGX enclave 中运行。它基于 Microsoft Research 的机密联盟框架。

请严重依赖服务的文档和我们的 Rest 客户端文档来使用此库

关键链接：

入门

目前支持的环境

Node.js版本 14.x.x 或更高版本

先决条件

一个 Azure 订阅。
Azure 机密账本的运行实例。
机密账本中的注册用户，通常在 ARM 资源创建期间分配，具有 Administrator 特权。

安装 `@azure-rest/confidential-ledger` 包

使用 npm安装适用于 JavaScript 的 Azure Condifential Ledger REST 客户端库：

npm install @azure-rest/confidential-ledger

创建客户端并对其进行身份验证

使用 Azure Active Directory

本文档演示如何使用 DefaultAzureCredential 通过 Azure Active Directory 向机密账本进行身份验证。可以在 Azure 门户中找到环境变量。但是， ConfidentialLedger 接受任何 @azure/标识凭据。

DefaultAzureCredential 将自动处理大多数 Azure SDK 客户端方案。若要开始，请将 AAD 应用程序的客户端 ID、租户 ID 和客户端密码的值设置为环境变量： AZURE_CLIENT_ID、 AZURE_TENANT_ID、 AZURE_CLIENT_SECRET。

然后， DefaultAzureCredential 将能够对客户端进行身份验证 ConfidentialLedger 。

创建客户端还需要机密账本的 URL 和 ID，可以从 Azure CLI 或 Azure 门户获取。

由于机密账本使用安全生成并存储在 enclave 中的自签名证书，因此必须先从机密账本标识服务检索每个机密账本的签名证书。

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

使用客户端证书

作为 Azure Active Directory 的替代方法，客户端可以选择使用相互 TLS 中的客户端证书进行身份验证，而不是通过 Azure Active Directory 令牌进行身份验证。对于此类身份验证，需要传递客户端， CertificateCredential 该客户端由 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,
      },
    });

关键概念

账本条目和事务

每次写入 Azure 机密账本都会在服务中生成不可变账本条目。写入（也称为事务）由事务 ID 唯一标识，这些 ID 随每次写入而递增。写入后，可以随时检索账本条目。

Receipts

机密账本的状态更改保存在名为 Merkle 树的数据结构中。若要以加密方式验证写入是否正确保存，可以检索任何事务 ID 的 Merkle 证明或收据。

集合

虽然大多数用例将涉及一个账本，但我们提供了收集功能，以防语义或逻辑上不同的数据组需要存储在同一机密账本中。

账本条目按其集合标识符检索。对于未指定集合的提交项，机密账本将始终采用由服务确定的常量集合 ID。

用户

用户直接使用机密账本进行管理，而不是通过 Azure 进行管理。用户可能基于 AAD，由其 AAD 对象 ID 标识，或基于证书，由其 PEM 证书指纹标识。

机密计算

Azure 机密计算允许在云中处理数据时隔离和保护数据。 Azure 机密账本在 Azure 机密计算虚拟机上运行，从而通过加密正在使用的数据提供更强大的数据保护。

机密联盟框架

Azure 机密账本基于 Microsoft Research 的开源机密联盟框架 (CCF) 。根据 CCF，应用程序由成员组成的联盟管理，这些成员能够提交修改和管理应用程序操作的建议。在 Azure 机密账本中，Microsoft Azure 拥有成员标识，允许其执行治理操作，例如替换机密账本中的不正常节点或升级 enclave 代码。

示例

本部分包含以下示例的代码片段：

后账本条目
按事务 ID 获取账本条目
获取所有账本条目
获取所有集合
获取集合的事务
列出 Enclave 引号

后账本条目

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

按事务 ID 获取账本条目

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

获取所有账本条目

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

获取所有集合

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

获取集合的事务

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

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

完整示例

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

疑难解答

日志记录

启用日志记录可能有助于发现有关故障的有用信息。若要查看 HTTP 请求和响应的日志，请将 AZURE_LOG_LEVEL 环境变量设置为 info。或者，可以在运行时通过调用 @azure/logger 中的 setLogLevel 来启用日志记录：

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

setLogLevel("info");

有关如何启用日志的更详细说明，请查看 @azure/logger 包文档。

后续步骤

请查看示例目录，获取有关如何使用此库的详细示例。

贡献

若要为此库做出贡献，请阅读贡献指南，详细了解如何生成和测试代码。

Microsoft Azure SDK for JavaScript

曝光数

通过