JavaScript용 Azure Confidential Ledger REST 클라이언트 라이브러리 - 버전 1.0.0

Azure Confidential Ledger는 변경할 수 없는 변조 방지 원장에 로깅하기 위한 서비스를 제공합니다. Azure Confidential Computing 포트폴리오의 일부로 Azure Confidential Ledger는 SGX Enclave에서 실행됩니다. Microsoft Research의 기밀 컨소시엄 프레임워크를 기반으로 합니다.

이 라이브러리를 사용하려면 서비스의 설명서 와 Rest 클라이언트 문서에 크게 의존하세요.

주요 링크:

• 소스 코드
• 패키지(NPM)
• API 참조 설명서
• 제품 설명서

시작

현재 지원되는 환경

• Node.js 버전 14.x.x 이상

필수 구성 요소

• Azure 구독.
• Azure Confidential Ledger의 실행 중인 인스턴스.
• 일반적으로 ARM 리소스를 만드는 동안 권한으로 Administrator 할당되는 Confidential Ledger에 등록된 사용자입니다.

@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 할 수 있습니다.

클라이언트를 만들려면 Azure CLI 또는 Azure Portal에서 가져올 수 있는 Confidential Ledger의 URL 및 ID도 필요합니다.

Confidential Ledger는 Enclave에 안전하게 생성되고 저장된 자체 서명된 인증서를 사용하므로 먼저 각 Confidential Ledger에 대한 서명 인증서를 Confidential Ledger ID 서비스에서 검색해야 합니다.

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 증명 또는 영수증을 검색할 수 있습니다.

컬렉션

대부분의 사용 사례에는 하나의 원장이 포함되지만 의미 체계 또는 논리적으로 다른 데이터 그룹을 동일한 Confidential Ledger에 저장해야 하는 경우 컬렉션 기능을 제공합니다.

원장 항목은 컬렉션 식별자에 의해 검색됩니다. Confidential Ledger는 항상 지정된 컬렉션 없이 제출된 항목에 대해 상수 서비스 결정 컬렉션 ID를 가정합니다.

사용자

사용자는 Azure를 통해서가 아니라 Confidential Ledger로 직접 관리됩니다. 사용자는 해당 PEM 인증서 지문으로 식별된 AAD 기반, AAD 개체 ID 또는 인증서 기반일 수 있습니다.

기밀 컴퓨팅

Azure 기밀 컴퓨팅 을 사용하면 클라우드에서 처리되는 동안 데이터를 격리하고 보호할 수 있습니다. Azure Confidential Ledger는 Azure Confidential Computing 가상 머신에서 실행되므로 사용 중인 데이터의 암호화를 통해 더 강력한 데이터 보호를 제공합니다.

기밀 컨소시엄 프레임워크

Azure Confidential Ledger는 Microsoft Research의 오픈 소스 CCF(기밀 컨소시엄 프레임워크)를 기반으로 합니다. CCF에서 애플리케이션은 애플리케이션 작업을 수정하고 제어하는 제안을 제출할 수 있는 멤버 컨소시엄에 의해 관리됩니다. Azure Confidential Ledger에서 Microsoft Azure는 멤버 ID를 소유하므로 기밀 원장의 비정상 노드를 교체하거나 enclave 코드를 업그레이드하는 것과 같은 거버넌스 작업을 수행할 수 있습니다.

예제

이 섹션에는 다음 샘플에 대한 코드 조각이 포함되어 있습니다.

• Post Ledger 항목
• 트랜잭션 ID로 원장 항목 가져오기
• 모든 원장 항목 가져오기
• 모든 컬렉션 가져오기
• 컬렉션에 대한 트랜잭션 가져오기
• Enclave 따옴표 나열

Post Ledger 항목

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 package docs를 참조하세요.

다음 단계

이 라이브러리를 사용하는 방법에 대한 자세한 예제는 샘플 디렉터리를 참조하세요.

참여

이 라이브러리에 기여하려면 기여 가이드 를 참조하여 코드를 빌드하고 테스트하는 방법에 대해 자세히 알아보세요.

관련된 프로젝트

• JavaScript용 Microsoft Azure SDK