通过

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

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

  • 项目

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 代码。

示例

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

后账本条目

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 包文档。

后续步骤

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

贡献

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

曝光数