共用方式為

適用于 JavaScript 的 Azure 機密總帳 REST 用戶端程式庫 - 1.0.0 版

  • 發行項

Azure 機密總帳提供服務，以記錄到不可變、防竄改的總帳。 作為 Azure 機密運算 組合的一部分，Azure 機密總帳會在 SGX 記憶體保護區中執行。 它是以 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 應用程式的用戶端識別碼、租使用者識別碼和用戶端密碼的值設定為環境變數： AZURE_CLIENT_ID 、、 AZURE_TENANT_IDAZURE_CLIENT_SECRET 。

然後， DefaultAzureCredential 將能夠驗證 ConfidentialLedger 用戶端。

建立用戶端也需要機密總帳的 URL 和識別碼，您可以從 Azure CLI 或 Azure 入口網站取得。

由於機密總帳會使用安全地產生並儲存在記憶體保護區中的自我簽署憑證，因此必須先從機密總帳識別服務擷取每個機密總帳的簽署憑證。

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 機密總帳都會在服務中產生不可變的總帳專案。 寫入也稱為交易，會以每次寫入遞增的交易識別碼來唯一識別。 寫入之後，隨時都可以擷取總帳專案。

Receipts

機密總帳的狀態變更會儲存在稱為 Merkle 樹狀結構的資料結構中。 若要以密碼編譯方式確認已正確儲存寫入，可以針對任何交易識別碼擷取 Merkle 證明或收據。

集合

雖然大部分的使用案例都會牽涉到一個總帳，但我們會提供集合功能，以防語意或邏輯上不同的資料群組必須儲存在相同的機密總帳中。

總帳專案是由其集合識別碼擷取。 機密總帳一律會假設未指定集合之專案的常數、服務決定的集合識別碼。

使用者

使用者會直接使用機密總帳來管理，而不是透過 Azure 來管理。 使用者可能是 AAD 型，由其 AAD 物件識別碼識別，或以憑證為基礎，由其 PEM 憑證指紋識別。

機密運算

Azure 機密運算 可讓您在雲端處理資料時隔離並保護資料。 Azure 機密總帳會在 Azure 機密運算虛擬機器上執行，藉由加密使用中的資料來提供更強的資料保護。

機密聯盟架構

Azure 機密總帳是以 Microsoft Research 的開放原始碼 機密聯盟架構為基礎， (CCF) 。 在 CCF 下，應用程式是由成員聯盟管理，能夠提交提案以修改和管理應用程式作業。 在 Azure 機密總帳中，Microsoft Azure 擁有成員身分識別，讓其能夠執行治理動作，例如取代機密總帳中的狀況不良節點，或升級記憶體保護區程式碼。

範例

本節包含下列範例的程式碼片段：

總帳後項目

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

依交易識別碼取得總帳專案

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

列出記憶體保護區引號

// 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 套件文件。

下一步

如需如何使用此程式庫的詳細 範例 ，請參閱範例目錄。

參與

如果您希望向此程式庫投稿，請參閱投稿指南，深入瞭解如何組建與測試程式碼。

曝光數