JavaScript 用 Azure Confidential Ledger REST クライアントライブラリ - バージョン 1.0.0

[アーティクル]
04/05/2023

Azure Confidential Ledger は、不変の改ざん防止台帳にログを記録するためのサービスを提供します。 Azure Confidential Computing ポートフォリオの一部として、Azure Confidential Ledger は SGX エンクレーブで実行されます。これは、Microsoft Research の Confidential Consortium Framework に基づいて構築されています。

このライブラリを使用するには、サービスのドキュメントと Rest クライアントのドキュメントに大きく依存してください

主要リンク:

作業の開始

現在サポートされている環境

Node.js バージョン 14.x.x 以降

前提条件

Azure サブスクリプション。
Azure Confidential Ledger の実行インスタンス。
Confidential Ledger に登録されているユーザー。通常は、ARM リソースの作成時に特権を持つ Administrator 割り当てられます。

`@azure-rest/confidential-ledger` パッケージのインストール

を使用して、JavaScript 用の Azure Condifential Ledger REST クライアントライブラリを npmインストールします。

npm install @azure-rest/confidential-ledger

クライアントの作成と認証

Azure Active Directory の使用

このドキュメントでは、 DefaultAzureCredential を使用して、Azure Active Directory 経由で Confidential Ledger に対する認証を行う方法について説明します。環境変数は、Azure Portal で確認できます。ただし、 ConfidentialLedger任意の@azure/ID 資格情報を受け入れます。

DefaultAzureCredential は、ほとんどの Azure SDK クライアントシナリオを自動的に処理します。まず、AAD アプリケーションのクライアント ID、テナント ID、およびクライアントシークレットの値を環境変数 AZURE_CLIENT_ID(、、AZURE_TENANT_IDAZURE_CLIENT_SECRET) として設定します。

その後、 DefaultAzureCredential クライアントを認証 ConfidentialLedger できるようになります。

クライアントを作成するには、Confidential Ledger の URL と ID も必要です。この URL は、Azure CLI または Azure Portal から取得できます。

Confidential Ledger は安全に生成され、エンクレーブに格納された自己署名証明書を使用するため、各 Confidential Ledger の署名証明書は、まず 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);

クライアント証明書の使用

Azure Active Directory の代わりに、クライアントは、Azure Active Directory トークンを使用する代わりに、相互 TLS でクライアント証明書を使用して認証することを選択できます。この種の認証では、証明書と秘密キーで構成される 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 Confidential Ledger へのすべての書き込みでは、サービスに不変の台帳エントリが生成されます。書き込み (トランザクションとも呼ばれます) は、書き込みごとにインクリメントされるトランザクション ID によって一意に識別されます。書き込まれた台帳エントリは、いつでも取得できます。

Receipts

Confidential Ledger に対する状態の変更は、Merkle ツリーと呼ばれるデータ構造に保存されます。書き込みが正しく保存されたことを暗号で確認するために、任意のトランザクション ID に対して Merkle の証明または領収書を取得できます。

コレクション

ほとんどのユースケースには 1 つの台帳が含まれますが、意味的または論理的に異なるデータグループを同じ Confidential Ledger に格納する必要がある場合に備えて、収集機能を提供します。

台帳エントリは、コレクション識別子によって取得されます。 Confidential Ledger は、常に、コレクションを指定せずに送信されたエントリに対して、サービスによって決定される定数のコレクション ID を想定します。

ユーザー

ユーザーは、Azure ではなく Confidential Ledger を使用して直接管理されます。ユーザーは、AAD ベースであり、AAD オブジェクト ID で識別されるか、PEM 証明書フィンガープリントによって識別される証明書ベースである場合があります。

コンフィデンシャルコンピューティング

Azure Confidential Computing を使用すると、クラウドで処理されている間にデータを分離して保護できます。 Azure Confidential Ledger は Azure Confidential Computing 仮想マシン上で実行されるため、使用中のデータの暗号化によるデータ保護が強化されます。

Confidential Consortium Framework

Azure Confidential Ledger は、Microsoft Research のオープンソースの Confidential Consortium Framework (CCF) 上に構築されています。 CCF では、アプリケーションはメンバーのコンソーシアムによって管理され、アプリケーション操作を変更および管理するための提案を送信できます。 Azure Confidential Ledger では、Microsoft Azure はメンバー ID を所有しているため、Confidential Ledger 内の異常なノードの置き換えやエンクレーブコードのアップグレードなどのガバナンスアクションを実行できます。

例

このセクションには、次のサンプルのコードスニペットが含まれています。

台帳エントリの転記
するトランザクション ID で台帳エントリを取得する
すべての台帳エントリを取得する
すべてのコレクションを取得する
するコレクションのトランザクションを取得する
エンクレーブ引用符を一覧表示する

台帳エントリの転記

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

エンクレーブ引用符を一覧表示する

// 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 パッケージに関するドキュメントを参照してください。

次の手順

このライブラリの使用方法の詳細な例については、 samples ディレクトリを参照してください。

共同作成

このライブラリに投稿する場合、コードをビルドしてテストする方法の詳細については、投稿ガイドを参照してください。

Microsoft Azure SDK for JavaScript

インプレッション数

次の方法で共有

JavaScript 用 Azure Confidential Ledger REST クライアントライブラリ - バージョン 1.0.0

作業の開始

現在サポートされている環境

前提条件

`@azure-rest/confidential-ledger` パッケージのインストール

クライアントの作成と認証

Azure Active Directory の使用

クライアント証明書の使用

主要な概念

台帳エントリとトランザクション

Receipts

コレクション

ユーザー

コンフィデンシャルコンピューティング

Confidential Consortium Framework

例

台帳エントリの転記

トランザクション ID で台帳エントリを取得する

すべての台帳エントリを取得する

すべてのコレクションを取得する

コレクションのトランザクションを取得する

エンクレーブ引用符を一覧表示する

完全な例

トラブルシューティング

ログ記録

次の手順

共同作成

その他のリソース

次の方法で共有

JavaScript 用 Azure Confidential Ledger REST クライアント ライブラリ - バージョン 1.0.0

作業の開始

現在サポートされている環境

前提条件

@azure-rest/confidential-ledger パッケージのインストール

クライアントの作成と認証

Azure Active Directory の使用

クライアント証明書の使用

主要な概念

台帳エントリとトランザクション

Receipts

コレクション

ユーザー

コンフィデンシャル コンピューティング

Confidential Consortium Framework

例

台帳エントリの転記

トランザクション ID で台帳エントリを取得する

すべての台帳エントリを取得する

すべてのコレクションを取得する

コレクションのトランザクションを取得する

エンクレーブ引用符を一覧表示する

完全な例

トラブルシューティング

ログ記録

次の手順

共同作成

関連プロジェクト

その他のリソース

JavaScript 用 Azure Confidential Ledger REST クライアントライブラリ - バージョン 1.0.0

`@azure-rest/confidential-ledger` パッケージのインストール

コンフィデンシャルコンピューティング