Bagikan melalui

Pustaka klien REST Azure Confidential Ledger untuk JavaScript - versi 1.0.0

  • Artikel

Azure Confidential Ledger menyediakan layanan untuk pengelogan ke ledger tahan perubahan yang tidak dapat diubah. Sebagai bagian dari portofolio Azure Confidential Computing , Azure Confidential Ledger berjalan di enklave SGX. Ini dibangun di atas Kerangka Kerja Konsorsium Rahasia Microsoft Research.

Harap sangat bergantung pada dokumentasi layanan dan dokumen klien Rest kami untuk menggunakan pustaka ini

Tautan utama:

Memulai

Lingkungan yang didukung saat ini

  • Node.js versi 14.x.x atau yang lebih tinggi

Prasyarat

  • Langganan Azure.
  • Instans yang berjalan Azure Confidential Ledger.
  • Pengguna terdaftar di Confidential Ledger, biasanya ditetapkan selama pembuatan sumber daya ARM , dengan Administrator hak istimewa.

Pasang paket @azure-rest/confidential-ledger

Instal pustaka klien Rest Azure Condifential Ledger untuk JavaScript dengan npm:

npm install @azure-rest/confidential-ledger

Membuat dan Mengautentikasi klien

Atau menggunakan Azure Active Directory

Dokumen ini menunjukkan penggunaan DefaultAzureCredential untuk mengautentikasi ke Confidential Ledger melalui Azure Active Directory. Anda dapat menemukan variabel lingkungan di Portal Microsoft Azure. Namun, ConfidentialLedger menerima kredensial @azure/identitas apa pun.

DefaultAzureCredential akan secara otomatis menangani sebagian besar skenario klien Azure SDK. Untuk memulai, atur nilai ID klien, ID penyewa, dan rahasia klien aplikasi AAD sebagai variabel lingkungan: AZURE_CLIENT_ID, , AZURE_TENANT_IDAZURE_CLIENT_SECRET.

Kemudian, DefaultAzureCredential akan dapat mengautentikasi ConfidentialLedger klien.

Membuat klien juga memerlukan URL dan id Confidential Ledger Anda, yang bisa Anda dapatkan dari Azure CLI atau Portal Microsoft Azure.

Karena Confidential Ledgers menggunakan sertifikat yang ditandatangani sendiri dengan aman yang dihasilkan dan disimpan dalam enklave, sertifikat penandatanganan untuk setiap Confidential Ledger harus terlebih dahulu diambil dari 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);

Menggunakan sertifikat klien

Sebagai alternatif untuk Azure Active Directory, klien dapat memilih untuk mengautentikasi dengan sertifikat klien di TLS bersama alih-alih melalui token Azure Active Directory. Untuk autentikasi semacam ini, klien perlu diteruskan CertificateCredential yang terdiri dari sertifikat dan kunci privat, baik dalam format 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,
      },
    });

Konsep utama

Entri dan transaksi ledger

Setiap penulisan ke Azure Confidential Ledger menghasilkan entri ledger yang tidak dapat diubah dalam layanan. Tulisan, juga disebut sebagai transaksi, secara unik diidentifikasi oleh id transaksi yang bertambah dengan setiap tulisan. Setelah ditulis, entri ledger dapat diambil kapan saja.

Tanda terima

Perubahan status pada Confidential Ledger disimpan dalam struktur data yang disebut pohon Merkle. Untuk memverifikasi secara kriptografis bahwa tulisan disimpan dengan benar, bukti Merkle, atau tanda terima, dapat diambil untuk id transaksi apa pun.

Koleksi

Meskipun sebagian besar kasus penggunaan akan melibatkan satu ledger, kami menyediakan fitur pengumpulan jika secara semantik atau logis kelompok data yang berbeda perlu disimpan dalam Confidential Ledger yang sama.

Entri ledger diambil oleh pengidentifikasi koleksinya. Confidential Ledger akan selalu mengasumsikan id koleksi yang konstan dan ditentukan layanan untuk entri yang dikirimkan tanpa koleksi yang ditentukan.

Pengguna

Pengguna dikelola langsung dengan Confidential Ledger alih-alih melalui Azure. Pengguna mungkin berbasis AAD, diidentifikasi oleh id objek AAD mereka, atau berbasis sertifikat, yang diidentifikasi oleh sidik jari sertifikat PEM mereka.

Komputasi rahasia

Azure Confidential Computing memungkinkan Anda mengisolasi dan melindungi data saat sedang diproses di cloud. Azure Confidential Ledger berjalan pada komputer virtual Azure Confidential Computing, sehingga memberikan perlindungan data yang lebih kuat dengan enkripsi data yang digunakan.

Kerangka Kerja Konsorsium Rahasia

Azure Confidential Ledger dibangun di atas Confidential Consortium Framework (CCF) sumber terbuka Microsoft Research. Di bawah CCF, aplikasi dikelola oleh konsorsium anggota dengan kemampuan untuk mengirimkan proposal untuk memodifikasi dan mengatur operasi aplikasi. Di Azure Confidential Ledger, Microsoft Azure memiliki identitas anggota, memungkinkannya melakukan tindakan tata kelola seperti mengganti simpul yang tidak sehat di Confidential Ledger, atau meningkatkan kode enklave.

Contoh

Bagian ini berisi cuplikan kode untuk sampel berikut:

Entri Post Ledger

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

Dapatkan Entri Ledger Berdasarkan Id Transaksi

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

Dapatkan Semua Entri Ledger

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

Dapatkan Semua Koleksi

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

Mendapatkan Transaksi untuk Koleksi

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

Cantumkan Kutipan Enklave

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

Contoh Lengkap

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

Pemecahan Masalah

Pencatatan

Mengaktifkan pengelogan dapat membantu menemukan informasi yang berguna tentang kegagalan. Untuk melihat log permintaan dan respons HTTP, atur variabel lingkungan AZURE_LOG_LEVEL ke info. Atau, pengelogan dapat diaktifkan saat runtime dengan memanggil setLogLevel di @azure/logger:

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

setLogLevel("info");

Untuk instruksi lebih rinci tentang cara mengaktifkan log, Anda dapat melihat dokumen paket @azure/pencatat.

Langkah berikutnya

Silakan lihat direktori sampel untuk contoh terperinci tentang cara menggunakan pustaka ini.

Berkontribusi

Jika Anda ingin berkontribusi pada pustaka ini, baca panduan berkontribusi untuk mempelajari selengkapnya tentang cara membuat dan menguji kode.

Tayangan