Pustaka klien REST Azure Confidential Ledger untuk JavaScript - versi 1.0.0
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_ID
AZURE_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
- Dapatkan Entri Ledger Berdasarkan Id Transaksi
- Dapatkan Semua Entri Ledger
- Dapatkan Semua Koleksi
- Mendapatkan Transaksi untuk Koleksi
- Cantumkan Kutipan Enklave
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.
Proyek terkait
Azure SDK for JavaScript